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