tor-browser

pkix_revchecker.h (8199B)

---

/* 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 */