1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_revchecker.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,217 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines functions associated with the PKIX_RevocationChecker
1.9 + * type.
1.10 + *
1.11 + */
1.12 +
1.13 +#ifndef _PKIX_REVCHECKER_H
1.14 +#define _PKIX_REVCHECKER_H
1.15 +
1.16 +#include "pkixt.h"
1.17 +#include "pkix_pl_pki.h"
1.18 +
1.19 +#ifdef __cplusplus
1.20 +extern "C" {
1.21 +#endif
1.22 +
1.23 +/* General
1.24 + *
1.25 + * Please refer to the libpkix Programmer's Guide for detailed information
1.26 + * about how to use the libpkix library. Certain key warnings and notices from
1.27 + * that document are repeated here for emphasis.
1.28 + *
1.29 + * All identifiers in this file (and all public identifiers defined in
1.30 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.31 + * within the library begin with "pkix_".
1.32 + *
1.33 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.34 + *
1.35 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.36 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.37 + * shared object. Therefore, the caller should treat this shared object as
1.38 + * read-only and should not modify this shared object. When done using the
1.39 + * shared object, the caller should release the reference to the object by
1.40 + * using the PKIX_PL_Object_DecRef function.
1.41 + *
1.42 + * While a function is executing, if its arguments (or anything referred to by
1.43 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.44 + * is undefined.
1.45 + *
1.46 + */
1.47 +
1.48 +/* PKIX_RevocationChecker
1.49 + *
1.50 + * PKIX_RevocationChecker provides a standard way of revocation checking.
1.51 + * Caller should configure two set of tests(represented at lists of
1.52 + * RevocationMethod objects) to be performed on the leaf and on the rest of
1.53 + * the chain certificates.
1.54 + *
1.55 + * PKIX_RevocationMethods provide a standard way for the caller to insert
1.56 + * their own custom revocation checks to verify the revocation status of
1.57 + * certificates. This may be useful in many scenarios, including when the
1.58 + * caller wishes to use their own revocation checking mechanism instead of (or
1.59 + * in addition to) the default revocation checking mechanism provided by
1.60 + * libpkix, which uses CRLs and OCSP.
1.61 + *
1.62 + * Once the caller has created the RevocationMethod object(s), the caller
1.63 + * then specifies the RevocationMethod object(s) in a RevocationCheck object
1.64 + * and sets it into a ProcessingParams.
1.65 + */
1.66 +
1.67 +/*
1.68 + * FUNCTION: PKIX_RevocationChecker_Create
1.69 + * DESCRIPTION:
1.70 + *
1.71 + * Creates revocation checker object with a given flags.
1.72 + *
1.73 + * PARAMETERS:
1.74 + * "revDate"
1.75 + * Revocation will be checked at this date. Current date is taken if the
1.76 + * parameter is not specified.
1.77 + * "leafMethodListFlags"
1.78 + * Defines a set of method independent flags that will be used to check
1.79 + * revocation of the leaf cert in the chain.
1.80 + * "chainMethodListFlags"
1.81 + * Defines a set of method independent flags that will be used to check
1.82 + * revocation of the remaining certs in the chain.
1.83 + * "pChecker"
1.84 + * The return address of created checker.
1.85 + * "plContext"
1.86 + * Platform-specific context pointer.
1.87 + * THREAD SAFETY:
1.88 + * Thread Safe
1.89 + *
1.90 + * Multiple threads must be able to safely call this function without
1.91 + * worrying about conflicts, even if they're operating on the same objects.
1.92 + * RETURNS:
1.93 + * Returns NULL if the function succeeds.
1.94 + * Returns a RevocationChecker Error if the function fails in a non-fatal way.
1.95 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.96 + */
1.97 +PKIX_Error *
1.98 +PKIX_RevocationChecker_Create(
1.99 + PKIX_UInt32 leafMethodListFlags,
1.100 + PKIX_UInt32 chainMethodListFlags,
1.101 + PKIX_RevocationChecker **pChecker,
1.102 + void *plContext);
1.103 +
1.104 +/*
1.105 + * FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
1.106 + * DESCRIPTION:
1.107 + *
1.108 + * Creates revocation method object with given parameters and adds it
1.109 + * to revocation checker method list.
1.110 + *
1.111 + * PARAMETERS:
1.112 + * "revChecker"
1.113 + * Address of revocation checker structure.
1.114 + * "procParams"
1.115 + * Address of ProcessingParams used to initialize the checker.
1.116 + * Must be non-NULL.
1.117 + * "methodType"
1.118 + * Type of the method. Currently only two types are
1.119 + * supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
1.120 + * "methodFlags"
1.121 + * Set of flags for the method.
1.122 + * "methodPriority"
1.123 + * Method priority. (0 corresponds to a highest priority)
1.124 + * "verificationFn"
1.125 + * User call back function that will perform validation of fetched
1.126 + * revocation information(new crl or ocsp response)
1.127 + * "isLeafMethod"
1.128 + * Boolean flag that if set to true indicates that the method should
1.129 + * should be used for leaf cert revocation test(false for chain set
1.130 + * methods).
1.131 + * "plContext"
1.132 + * Platform-specific context pointer.
1.133 + * THREAD SAFETY:
1.134 + * Thread Safe
1.135 + *
1.136 + * Multiple threads must be able to safely call this function without
1.137 + * worrying about conflicts, even if they're operating on the same objects.
1.138 + * RETURNS:
1.139 + * Returns NULL if the function succeeds.
1.140 + * Returns a RevocationChecker Error if the function fails in a non-fatal way.
1.141 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.142 + */
1.143 +PKIX_Error *
1.144 +PKIX_RevocationChecker_CreateAndAddMethod(
1.145 + PKIX_RevocationChecker *revChecker,
1.146 + PKIX_ProcessingParams *params,
1.147 + PKIX_RevocationMethodType methodType,
1.148 + PKIX_UInt32 methodFlags,
1.149 + PKIX_UInt32 mathodPriority,
1.150 + PKIX_PL_VerifyCallback verificationFn,
1.151 + PKIX_Boolean isLeafMethod,
1.152 + void *plContext);
1.153 +
1.154 +/*
1.155 + * FUNCTION: PKIX_RevocationChecker_Check
1.156 + * DESCRIPTION:
1.157 + *
1.158 + * Verifies revocation status of the certificate. Issuer cert is given to
1.159 + * be used in verification of revocation information. Performed verification
1.160 + * check depends on configured revocation methods(ocsp, crl. See
1.161 + * PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
1.162 + * building process at which PKIX_RevocationChecker_Check was invoked.
1.163 + * For security reasons, the cert status is checked only against cached
1.164 + * revocation information during chain building stage(no trust anchor yes has
1.165 + * been found). The fresh revocation information fetching is done only at chain
1.166 + * verification stage after trust anchor was identified.
1.167 + *
1.168 + * PARAMETERS:
1.169 + * "cert"
1.170 + * Address of Cert whose revocation status is to be determined.
1.171 + * Must be non-NULL.
1.172 + * "issuer"
1.173 + * Issuer cert that potentially holds public key that will be used
1.174 + * to verify revocation info.
1.175 + * "revChecker"
1.176 + * Address of revocation checker structure.
1.177 + * "procParams"
1.178 + * Address of ProcessingParams used to initialize the checker.
1.179 + * Must be non-NULL.
1.180 + * "chainVerificationState"
1.181 + * Need to be set to true, if the check was called during chain verification
1.182 + * as an opposite to chain building.
1.183 + * "testingLeafCert"
1.184 + * Set to true if verifying revocation status of a leaf cert.
1.185 + * "revStatus"
1.186 + * Address of the returned revocation status of the cert.
1.187 + * "pResultCode"
1.188 + * Address where revocation status will be stored. Must be non-NULL.
1.189 + * "pNBIOContext"
1.190 + * Address at which platform-dependent non-blocking I/O context is stored.
1.191 + * Must be non-NULL.
1.192 + * "plContext"
1.193 + * Platform-specific context pointer.
1.194 + * THREAD SAFETY:
1.195 + * Thread Safe
1.196 + *
1.197 + * Multiple threads must be able to safely call this function without
1.198 + * worrying about conflicts, even if they're operating on the same objects.
1.199 + * RETURNS:
1.200 + * Returns NULL if the function succeeds.
1.201 + * Returns a RevocationChecker Error if the function fails in a non-fatal way.
1.202 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.203 + */
1.204 +PKIX_Error *
1.205 +PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
1.206 + PKIX_PL_Cert *issuer,
1.207 + PKIX_RevocationChecker *revChecker,
1.208 + PKIX_ProcessingParams *procParams,
1.209 + PKIX_Boolean chainVerificationState,
1.210 + PKIX_Boolean testingLeafCert,
1.211 + PKIX_RevocationStatus *revStatus,
1.212 + PKIX_UInt32 *pReasonCode,
1.213 + void **pNbioContext,
1.214 + void *plContext);
1.215 +
1.216 +#ifdef __cplusplus
1.217 +}
1.218 +#endif
1.219 +
1.220 +#endif /* _PKIX_REVCHECKER_H */
