diff options
Diffstat (limited to '')
-rw-r--r-- | security/nss/lib/libpkix/include/pkix_revchecker.h | 215 |
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 100644 index 0000000000..a16d23a933 --- /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 */ |