summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/libpkix/include/pkix_revchecker.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_revchecker.h')
-rwxr-xr-xsecurity/nss/lib/libpkix/include/pkix_revchecker.h215
1 files changed, 215 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_revchecker.h b/security/nss/lib/libpkix/include/pkix_revchecker.h
new file mode 100755
index 000000000..a16d23a93
--- /dev/null
+++ b/security/nss/lib/libpkix/include/pkix_revchecker.h
@@ -0,0 +1,215 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+/*
+ * This file defines functions associated with the PKIX_RevocationChecker
+ * type.
+ *
+ */
+
+#ifndef _PKIX_REVCHECKER_H
+#define _PKIX_REVCHECKER_H
+
+#include "pkixt.h"
+#include "pkix_pl_pki.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* General
+ *
+ * Please refer to the libpkix Programmer's Guide for detailed information
+ * about how to use the libpkix library. Certain key warnings and notices from
+ * that document are repeated here for emphasis.
+ *
+ * All identifiers in this file (and all public identifiers defined in
+ * libpkix) begin with "PKIX_". Private identifiers only intended for use
+ * within the library begin with "pkix_".
+ *
+ * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
+ *
+ * Unless otherwise noted, for all accessor (gettor) functions that return a
+ * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
+ * shared object. Therefore, the caller should treat this shared object as
+ * read-only and should not modify this shared object. When done using the
+ * shared object, the caller should release the reference to the object by
+ * using the PKIX_PL_Object_DecRef function.
+ *
+ * While a function is executing, if its arguments (or anything referred to by
+ * its arguments) are modified, free'd, or destroyed, the function's behavior
+ * is undefined.
+ *
+ */
+
+/* PKIX_RevocationChecker
+ *
+ * PKIX_RevocationChecker provides a standard way of revocation checking.
+ * Caller should configure two set of tests(represented at lists of
+ * RevocationMethod objects) to be performed on the leaf and on the rest of
+ * the chain certificates.
+ *
+ * PKIX_RevocationMethods provide a standard way for the caller to insert
+ * their own custom revocation checks to verify the revocation status of
+ * certificates. This may be useful in many scenarios, including when the
+ * caller wishes to use their own revocation checking mechanism instead of (or
+ * in addition to) the default revocation checking mechanism provided by
+ * libpkix, which uses CRLs and OCSP.
+ *
+ * Once the caller has created the RevocationMethod object(s), the caller
+ * then specifies the RevocationMethod object(s) in a RevocationCheck object
+ * and sets it into a ProcessingParams.
+ */
+
+/*
+ * FUNCTION: PKIX_RevocationChecker_Create
+ * DESCRIPTION:
+ *
+ * Creates a revocation checker object with the given flags. Revocation will
+ * be checked at the current date.
+ *
+ * PARAMETERS:
+ * "leafMethodListFlags"
+ * Defines a set of method independent flags that will be used to check
+ * revocation of the leaf cert in the chain.
+ * "chainMethodListFlags"
+ * Defines a set of method independent flags that will be used to check
+ * revocation of the remaining certs in the chain.
+ * "pChecker"
+ * The return address of created checker.
+ * "plContext"
+ * Platform-specific context pointer.
+ * THREAD SAFETY:
+ * Thread Safe
+ *
+ * Multiple threads must be able to safely call this function without
+ * worrying about conflicts, even if they're operating on the same objects.
+ * RETURNS:
+ * Returns NULL if the function succeeds.
+ * Returns a RevocationChecker Error if the function fails in a non-fatal way.
+ * Returns a Fatal Error if the function fails in an unrecoverable way.
+ */
+PKIX_Error *
+PKIX_RevocationChecker_Create(
+ PKIX_UInt32 leafMethodListFlags,
+ PKIX_UInt32 chainMethodListFlags,
+ PKIX_RevocationChecker **pChecker,
+ void *plContext);
+
+/*
+ * FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
+ * DESCRIPTION:
+ *
+ * Creates revocation method object with given parameters and adds it
+ * to revocation checker method list.
+ *
+ * PARAMETERS:
+ * "revChecker"
+ * Address of revocation checker structure.
+ * "procParams"
+ * Address of ProcessingParams used to initialize the checker.
+ * Must be non-NULL.
+ * "methodType"
+ * Type of the method. Currently only two types are
+ * supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
+ * "methodFlags"
+ * Set of flags for the method.
+ * "methodPriority"
+ * Method priority. (0 corresponds to the highest priority)
+ * "verificationFn"
+ * User call back function that will perform validation of fetched
+ * revocation information(new crl or ocsp response)
+ * "isLeafMethod"
+ * Boolean flag that if set to true indicates that the method should
+ * should be used for leaf cert revocation test(false for chain set
+ * methods).
+ * "plContext"
+ * Platform-specific context pointer.
+ * THREAD SAFETY:
+ * Thread Safe
+ *
+ * Multiple threads must be able to safely call this function without
+ * worrying about conflicts, even if they're operating on the same objects.
+ * RETURNS:
+ * Returns NULL if the function succeeds.
+ * Returns a RevocationChecker Error if the function fails in a non-fatal way.
+ * Returns a Fatal Error if the function fails in an unrecoverable way.
+ */
+PKIX_Error *
+PKIX_RevocationChecker_CreateAndAddMethod(
+ PKIX_RevocationChecker *revChecker,
+ PKIX_ProcessingParams *params,
+ PKIX_RevocationMethodType methodType,
+ PKIX_UInt32 methodFlags,
+ PKIX_UInt32 methodPriority,
+ PKIX_PL_VerifyCallback verificationFn,
+ PKIX_Boolean isLeafMethod,
+ void *plContext);
+
+/*
+ * FUNCTION: PKIX_RevocationChecker_Check
+ * DESCRIPTION:
+ *
+ * Verifies revocation status of the certificate. Issuer cert is given to
+ * be used in verification of revocation information. Performed verification
+ * check depends on configured revocation methods(ocsp, crl. See
+ * PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
+ * building process at which PKIX_RevocationChecker_Check was invoked.
+ * For security reasons, the cert status is checked only against cached
+ * revocation information during chain building stage(no trust anchor yes has
+ * been found). The fresh revocation information fetching is done only at chain
+ * verification stage after trust anchor was identified.
+ *
+ * PARAMETERS:
+ * "cert"
+ * Address of Cert whose revocation status is to be determined.
+ * Must be non-NULL.
+ * "issuer"
+ * Issuer cert that potentially holds public key that will be used
+ * to verify revocation info.
+ * "revChecker"
+ * Address of revocation checker structure.
+ * "procParams"
+ * Address of ProcessingParams used to initialize the checker.
+ * Must be non-NULL.
+ * "chainVerificationState"
+ * Need to be set to true, if the check was called during chain verification
+ * as an opposite to chain building.
+ * "testingLeafCert"
+ * Set to true if verifying revocation status of a leaf cert.
+ * "revStatus"
+ * Address of the returned revocation status of the cert.
+ * "pResultCode"
+ * Address where revocation status will be stored. Must be non-NULL.
+ * "pNBIOContext"
+ * Address at which platform-dependent non-blocking I/O context is stored.
+ * Must be non-NULL.
+ * "plContext"
+ * Platform-specific context pointer.
+ * THREAD SAFETY:
+ * Thread Safe
+ *
+ * Multiple threads must be able to safely call this function without
+ * worrying about conflicts, even if they're operating on the same objects.
+ * RETURNS:
+ * Returns NULL if the function succeeds.
+ * Returns a RevocationChecker Error if the function fails in a non-fatal way.
+ * Returns a Fatal Error if the function fails in an unrecoverable way.
+ */
+PKIX_Error *
+PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
+ PKIX_PL_Cert *issuer,
+ PKIX_RevocationChecker *revChecker,
+ PKIX_ProcessingParams *procParams,
+ PKIX_Boolean chainVerificationState,
+ PKIX_Boolean testingLeafCert,
+ PKIX_RevocationStatus *revStatus,
+ PKIX_UInt32 *pReasonCode,
+ void **pNbioContext,
+ void *plContext);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _PKIX_REVCHECKER_H */