security/nss/lib/libpkix/include/pkix_revchecker.h@b8a032363ba2
security/nss/lib/libpkix/include/pkix_revchecker.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rwxr-xr-x
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4 /*
5 * This file defines functions associated with the PKIX_RevocationChecker
6 * type.
7 *
8 */
10 #ifndef _PKIX_REVCHECKER_H
11 #define _PKIX_REVCHECKER_H
13 #include "pkixt.h"
14 #include "pkix_pl_pki.h"
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
20 /* General
21 *
22 * Please refer to the libpkix Programmer's Guide for detailed information
23 * about how to use the libpkix library. Certain key warnings and notices from
24 * that document are repeated here for emphasis.
25 *
26 * All identifiers in this file (and all public identifiers defined in
27 * libpkix) begin with "PKIX_". Private identifiers only intended for use
28 * within the library begin with "pkix_".
29 *
30 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
31 *
32 * Unless otherwise noted, for all accessor (gettor) functions that return a
33 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
34 * shared object. Therefore, the caller should treat this shared object as
35 * read-only and should not modify this shared object. When done using the
36 * shared object, the caller should release the reference to the object by
37 * using the PKIX_PL_Object_DecRef function.
38 *
39 * While a function is executing, if its arguments (or anything referred to by
40 * its arguments) are modified, free'd, or destroyed, the function's behavior
41 * is undefined.
42 *
43 */
45 /* PKIX_RevocationChecker
46 *
47 * PKIX_RevocationChecker provides a standard way of revocation checking.
48 * Caller should configure two set of tests(represented at lists of
49 * RevocationMethod objects) to be performed on the leaf and on the rest of
50 * the chain certificates.
51 *
52 * PKIX_RevocationMethods provide a standard way for the caller to insert
53 * their own custom revocation checks to verify the revocation status of
54 * certificates. This may be useful in many scenarios, including when the
55 * caller wishes to use their own revocation checking mechanism instead of (or
56 * in addition to) the default revocation checking mechanism provided by
57 * libpkix, which uses CRLs and OCSP.
58 *
59 * Once the caller has created the RevocationMethod object(s), the caller
60 * then specifies the RevocationMethod object(s) in a RevocationCheck object
61 * and sets it into a ProcessingParams.
62 */
64 /*
65 * FUNCTION: PKIX_RevocationChecker_Create
66 * DESCRIPTION:
67 *
68 * Creates revocation checker object with a given flags.
69 *
70 * PARAMETERS:
71 * "revDate"
72 * Revocation will be checked at this date. Current date is taken if the
73 * parameter is not specified.
74 * "leafMethodListFlags"
75 * Defines a set of method independent flags that will be used to check
76 * revocation of the leaf cert in the chain.
77 * "chainMethodListFlags"
78 * Defines a set of method independent flags that will be used to check
79 * revocation of the remaining certs in the chain.
80 * "pChecker"
81 * The return address of created checker.
82 * "plContext"
83 * Platform-specific context pointer.
84 * THREAD SAFETY:
85 * Thread Safe
86 *
87 * Multiple threads must be able to safely call this function without
88 * worrying about conflicts, even if they're operating on the same objects.
89 * RETURNS:
90 * Returns NULL if the function succeeds.
91 * Returns a RevocationChecker Error if the function fails in a non-fatal way.
92 * Returns a Fatal Error if the function fails in an unrecoverable way.
93 */
94 PKIX_Error *
95 PKIX_RevocationChecker_Create(
96 PKIX_UInt32 leafMethodListFlags,
97 PKIX_UInt32 chainMethodListFlags,
98 PKIX_RevocationChecker **pChecker,
99 void *plContext);
101 /*
102 * FUNCTION: PKIX_RevocationChecker_CreateAndAddMethod
103 * DESCRIPTION:
104 *
105 * Creates revocation method object with given parameters and adds it
106 * to revocation checker method list.
107 *
108 * PARAMETERS:
109 * "revChecker"
110 * Address of revocation checker structure.
111 * "procParams"
112 * Address of ProcessingParams used to initialize the checker.
113 * Must be non-NULL.
114 * "methodType"
115 * Type of the method. Currently only two types are
116 * supported: crl and ocsp. (See PKIX_RevocationMethodType enum).
117 * "methodFlags"
118 * Set of flags for the method.
119 * "methodPriority"
120 * Method priority. (0 corresponds to a highest priority)
121 * "verificationFn"
122 * User call back function that will perform validation of fetched
123 * revocation information(new crl or ocsp response)
124 * "isLeafMethod"
125 * Boolean flag that if set to true indicates that the method should
126 * should be used for leaf cert revocation test(false for chain set
127 * methods).
128 * "plContext"
129 * Platform-specific context pointer.
130 * THREAD SAFETY:
131 * Thread Safe
132 *
133 * Multiple threads must be able to safely call this function without
134 * worrying about conflicts, even if they're operating on the same objects.
135 * RETURNS:
136 * Returns NULL if the function succeeds.
137 * Returns a RevocationChecker Error if the function fails in a non-fatal way.
138 * Returns a Fatal Error if the function fails in an unrecoverable way.
139 */
140 PKIX_Error *
141 PKIX_RevocationChecker_CreateAndAddMethod(
142 PKIX_RevocationChecker *revChecker,
143 PKIX_ProcessingParams *params,
144 PKIX_RevocationMethodType methodType,
145 PKIX_UInt32 methodFlags,
146 PKIX_UInt32 mathodPriority,
147 PKIX_PL_VerifyCallback verificationFn,
148 PKIX_Boolean isLeafMethod,
149 void *plContext);
151 /*
152 * FUNCTION: PKIX_RevocationChecker_Check
153 * DESCRIPTION:
154 *
155 * Verifies revocation status of the certificate. Issuer cert is given to
156 * be used in verification of revocation information. Performed verification
157 * check depends on configured revocation methods(ocsp, crl. See
158 * PKIX_RevocationChecker_CreateAndAddMethod function) and a point of chain
159 * building process at which PKIX_RevocationChecker_Check was invoked.
160 * For security reasons, the cert status is checked only against cached
161 * revocation information during chain building stage(no trust anchor yes has
162 * been found). The fresh revocation information fetching is done only at chain
163 * verification stage after trust anchor was identified.
164 *
165 * PARAMETERS:
166 * "cert"
167 * Address of Cert whose revocation status is to be determined.
168 * Must be non-NULL.
169 * "issuer"
170 * Issuer cert that potentially holds public key that will be used
171 * to verify revocation info.
172 * "revChecker"
173 * Address of revocation checker structure.
174 * "procParams"
175 * Address of ProcessingParams used to initialize the checker.
176 * Must be non-NULL.
177 * "chainVerificationState"
178 * Need to be set to true, if the check was called during chain verification
179 * as an opposite to chain building.
180 * "testingLeafCert"
181 * Set to true if verifying revocation status of a leaf cert.
182 * "revStatus"
183 * Address of the returned revocation status of the cert.
184 * "pResultCode"
185 * Address where revocation status will be stored. Must be non-NULL.
186 * "pNBIOContext"
187 * Address at which platform-dependent non-blocking I/O context is stored.
188 * Must be non-NULL.
189 * "plContext"
190 * Platform-specific context pointer.
191 * THREAD SAFETY:
192 * Thread Safe
193 *
194 * Multiple threads must be able to safely call this function without
195 * worrying about conflicts, even if they're operating on the same objects.
196 * RETURNS:
197 * Returns NULL if the function succeeds.
198 * Returns a RevocationChecker Error if the function fails in a non-fatal way.
199 * Returns a Fatal Error if the function fails in an unrecoverable way.
200 */
201 PKIX_Error *
202 PKIX_RevocationChecker_Check(PKIX_PL_Cert *cert,
203 PKIX_PL_Cert *issuer,
204 PKIX_RevocationChecker *revChecker,
205 PKIX_ProcessingParams *procParams,
206 PKIX_Boolean chainVerificationState,
207 PKIX_Boolean testingLeafCert,
208 PKIX_RevocationStatus *revStatus,
209 PKIX_UInt32 *pReasonCode,
210 void **pNbioContext,
211 void *plContext);
213 #ifdef __cplusplus
214 }
215 #endif
217 #endif /* _PKIX_REVCHECKER_H */
