The Tor Browser / file comparison

comparison: security/nss/lib/libpkix/include/pkix_checker.h

security/nss/lib/libpkix/include/pkix_checker.h

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:d130622e34ea
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_CertChainChecker type.
6 *
7 */
8
9 #ifndef _PKIX_CHECKER_H
10 #define _PKIX_CHECKER_H
11
12 #include "pkixt.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /* General
19 *
20 * Please refer to the libpkix Programmer's Guide for detailed information
21 * about how to use the libpkix library. Certain key warnings and notices from
22 * that document are repeated here for emphasis.
23 *
24 * All identifiers in this file (and all public identifiers defined in
25 * libpkix) begin with "PKIX_". Private identifiers only intended for use
26 * within the library begin with "pkix_".
27 *
28 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
29 *
30 * Unless otherwise noted, for all accessor (gettor) functions that return a
31 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
32 * shared object. Therefore, the caller should treat this shared object as
33 * read-only and should not modify this shared object. When done using the
34 * shared object, the caller should release the reference to the object by
35 * using the PKIX_PL_Object_DecRef function.
36 *
37 * While a function is executing, if its arguments (or anything referred to by
38 * its arguments) are modified, free'd, or destroyed, the function's behavior
39 * is undefined.
40 *
41 */
42
43 /* PKIX_CertChainChecker
44 *
45 * PKIX_CertChainCheckers provide a standard way for the caller to insert their
46 * own custom checks to validate certificates. This may be useful in many
47 * scenarios, including when the caller wishes to validate private certificate
48 * extensions. The CheckCallback allows custom certificate processing to take
49 * place. Additionally, a CertChainChecker can optionally maintain state
50 * between successive calls to the CheckCallback. This certChainCheckerState
51 * must be an Object (although any object type), allowing it to be
52 * reference-counted and allowing it to provide the standard Object functions
53 * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes
54 * their CertChainChecker to be used during chain building, their
55 * certChainCheckerState object must implement an appropriate Duplicate
56 * function. The builder uses this Duplicate function when backtracking.
57 *
58 * Once the caller has created a CertChainChecker object, the caller then
59 * specifies a CertChainChecker object in a ProcessingParams object
60 * and passes the ProcessingParams object to PKIX_ValidateChain or
61 * PKIX_BuildChain, which uses the objects to call the user's callback
62 * functions as needed during the validation or building process.
63 *
64 * A CertChainChecker may be presented certificates in the "reverse" direction
65 * (from trust anchor to target) or in the "forward" direction (from target to
66 * trust anchor). All CertChainCheckers must support "reverse checking", while
67 * support for "forward checking" is optional, but recommended. If "forward
68 * checking" is not supported, building chains may be much less efficient. The
69 * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to
70 * determine whether forward checking is supported, and the
71 * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to
72 * determine whether the CertChainChecker has been initialized to expect the
73 * certificates to be presented in the "forward" direction.
74 */
75
76 /*
77 * FUNCTION: PKIX_CertChainChecker_CheckCallback
78 * DESCRIPTION:
79 *
80 * This callback function checks whether the specified Cert pointed to by
81 * "cert" is valid using "checker's" internal certChainCheckerState (if any)
82 * and removes the critical extensions that it processes (if any) from the
83 * List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions".
84 * If the checker finds that the certificate is not valid, an Error pointer is
85 * returned.
86 *
87 * If the checker uses non-blocking I/O, the address of a platform-dependent
88 * non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext",
89 * which the caller may use, in a platform-dependent way, to wait, poll, or
90 * otherwise determine when to try again. If the checker does not use
91 * non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL
92 * value was stored, on a subsequent call the checker will attempt to complete
93 * the pending I/O and, if successful, NULL will be stored at "pNBIOContext".
94 *
95 * PARAMETERS:
96 * "checker"
97 * Address of CertChainChecker whose certChainCheckerState and
98 * CheckCallback logic is to be used. Must be non-NULL.
99 * "cert"
100 * Address of Cert that is to be validated using "checker".
101 * Must be non-NULL.
102 * "unresolvedCriticalExtensions"
103 * Address of List of OIDs that represents the critical certificate
104 * extensions that have yet to be resolved. This parameter may be
105 * modified during the function call. Must be non-NULL.
106 * "pNBIOContext"
107 * Address at which is stored a platform-dependent structure indicating
108 * whether checking was suspended for non-blocking I/O. Must be non-NULL.
109 * "plContext"
110 * Platform-specific context pointer.
111 * THREAD SAFETY:
112 * Thread Safe
113 *
114 * Multiple threads must be able to safely call this function without
115 * worrying about conflicts, even if they're operating on the same object.
116 * RETURNS:
117 * Returns NULL if the function succeeds.
118 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
119 * Returns a Fatal Error if the function fails in an unrecoverable way.
120 */
121 typedef PKIX_Error *
122 (*PKIX_CertChainChecker_CheckCallback)(
123 PKIX_CertChainChecker *checker,
124 PKIX_PL_Cert *cert,
125 PKIX_List *unresolvedCriticalExtensions, /* list of PKIX_PL_OID */
126 void **pNBIOContext,
127 void *plContext);
128
129 /*
130 * FUNCTION: PKIX_CertChainChecker_Create
131 * DESCRIPTION:
132 *
133 * Creates a new CertChainChecker and stores it at "pChecker". The new
134 * CertChainChecker uses the CheckCallback pointed to by "callback" as its
135 * callback function. It uses the Object pointed to by "initialState" (if
136 * any) as its initial state. As noted above, the initial state Object must
137 * provide a custom implementation of PKIX_PL_Object_Duplicate if the
138 * CertChainChecker is to be used during certificate chain building.
139 *
140 * A CertChainChecker may be presented certificates in the "reverse"
141 * direction (from trust anchor to target) or in the "forward" direction
142 * (from target to trust anchor). All CertChainCheckers must support
143 * "reverse checking", while support for "forward checking" is optional. The
144 * CertChainChecker is initialized with two Boolean flags that deal with this
145 * distinction: "forwardCheckingSupported" and "forwardDirectionExpected".
146 * If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that
147 * this CertChainChecker is capable of checking certificates in the "forward"
148 * direction (as well as the "reverse" direction, which all CertChainCheckers
149 * MUST support). The "forwardDirectionExpected" Boolean flag indicates in
150 * which direction the CertChainChecker should expect the certificates to be
151 * presented. This is particularly useful for CertChainCheckers that are
152 * capable of checking in either the "forward" direction or the "reverse"
153 * direction, but have different processing steps depending on the direction.
154 *
155 * The CertChainChecker also uses the List of OIDs pointed to by "extensions"
156 * as the supported certificate extensions. All certificate extensions that
157 * the CertChainChecker might possibly recognize and be able to process
158 * should be included in the List of supported extensions. If "checker" does
159 * not recognize or process any certificate extensions, "extensions" should
160 * be set to NULL.
161 *
162 * PARAMETERS:
163 * "callback"
164 * The CheckCallback function to be used. Must be non-NULL.
165 * "forwardCheckingSupported"
166 * A Boolean value indicating whether or not this CertChainChecker is
167 * capable of checking certificates in the "forward" direction.
168 * "forwardDirectionExpected"
169 * A Boolean value indicating whether or not this CertChainChecker should
170 * be used to check in the "forward" direction.
171 * "extensions"
172 * Address of List of OIDs representing the supported extensions.
173 * "initialState"
174 * Address of Object representing the CertChainChecker's initial state
175 * (if any).
176 * "pChecker"
177 * Address where object pointer will be stored. Must be non-NULL.
178 * "plContext"
179 * Platform-specific context pointer.
180 * THREAD SAFETY:
181 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
182 * RETURNS:
183 * Returns NULL if the function succeeds.
184 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
185 * Returns a Fatal Error if the function fails in an unrecoverable way.
186 */
187 PKIX_Error *
188 PKIX_CertChainChecker_Create(
189 PKIX_CertChainChecker_CheckCallback callback,
190 PKIX_Boolean forwardCheckingSupported,
191 PKIX_Boolean forwardDirectionExpected,
192 PKIX_List *extensions, /* list of PKIX_PL_OID */
193 PKIX_PL_Object *initialState,
194 PKIX_CertChainChecker **pChecker,
195 void *plContext);
196
197 /*
198 * FUNCTION: PKIX_CertChainChecker_GetCheckCallback
199 * DESCRIPTION:
200 *
201 * Retrieves a pointer to "checker's" Check callback function and puts it in
202 * "pCallback".
203 *
204 * PARAMETERS:
205 * "checker"
206 * The CertChainChecker whose Check callback is desired. Must be non-NULL.
207 * "pCallback"
208 * Address where Check callback function pointer will be stored.
209 * Must be non-NULL.
210 * "plContext"
211 * Platform-specific context pointer.
212 * THREAD SAFETY:
213 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
214 * RETURNS:
215 * Returns NULL if the function succeeds.
216 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
217 * Returns a Fatal Error if the function fails in an unrecoverable way.
218 */
219 PKIX_Error *
220 PKIX_CertChainChecker_GetCheckCallback(
221 PKIX_CertChainChecker *checker,
222 PKIX_CertChainChecker_CheckCallback *pCallback,
223 void *plContext);
224
225 /*
226 * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported
227 * DESCRIPTION:
228 *
229 * Checks whether forward checking is supported by the CertChainChecker
230 * pointed to by "checker" and stores the Boolean result at
231 * "pForwardCheckingSupported".
232 *
233 * A CertChainChecker may be presented certificates in the "reverse"
234 * direction (from trust anchor to target) or in the "forward" direction
235 * (from target to trust anchor). All CertChainCheckers must support
236 * "reverse checking", while support for "forward checking" is optional. This
237 * function is used to determine whether forward checking is supported.
238 *
239 * PARAMETERS:
240 * "checker"
241 * The CertChainChecker whose ability to validate certificates in the
242 * "forward" direction is to be checked. Must be non-NULL.
243 * "pForwardCheckingSupported"
244 * Destination of the Boolean result. Must be non-NULL.
245 * "plContext"
246 * Platform-specific context pointer.
247 * THREAD SAFETY:
248 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
249 * RETURNS:
250 * Returns NULL if the function succeeds.
251 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
252 * Returns a Fatal Error if the function fails in an unrecoverable way.
253 */
254 PKIX_Error *
255 PKIX_CertChainChecker_IsForwardCheckingSupported(
256 PKIX_CertChainChecker *checker,
257 PKIX_Boolean *pForwardCheckingSupported,
258 void *plContext);
259
260 /*
261 * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected
262 * DESCRIPTION:
263 *
264 * Checks whether the CertChainChecker pointed to by "checker" has been
265 * initialized to expect the certificates to be presented in the "forward"
266 * direction and stores the Boolean result at "pForwardDirectionExpected".
267 *
268 * A CertChainChecker may be presented certificates in the "reverse"
269 * direction (from trust anchor to target) or in the "forward" direction
270 * (from target to trust anchor). All CertChainCheckers must support
271 * "reverse checking", while support for "forward checking" is optional. This
272 * function is used to determine in which direction the CertChainChecker
273 * expects the certificates to be presented.
274 *
275 * PARAMETERS:
276 * "checker"
277 * The CertChainChecker that has been initialized to expect certificates
278 * in either the "forward" or "reverse" directions. Must be non-NULL.
279 * "pForwardDirectionExpected"
280 * Destination of the Boolean result. Must be non-NULL.
281 * "plContext"
282 * Platform-specific context pointer.
283 * THREAD SAFETY:
284 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
285 * RETURNS:
286 * Returns NULL if the function succeeds.
287 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
288 * Returns a Fatal Error if the function fails in an unrecoverable way.
289 */
290 PKIX_Error *
291 PKIX_CertChainChecker_IsForwardDirectionExpected(
292 PKIX_CertChainChecker *checker,
293 PKIX_Boolean *pForwardDirectionExpected,
294 void *plContext);
295
296 /*
297 * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions
298 * DESCRIPTION:
299 *
300 * Retrieves a pointer to a List of OIDs (each OID corresponding to a
301 * certificate extension supported by the CertChainChecker pointed to by
302 * "checker") and stores it at "pExtensions". All certificate extensions that
303 * the CertChainChecker might possibly recognize and be able to process
304 * should be included in the List of supported extensions. If "checker" does
305 * not recognize or process any certificate extensions, this function stores
306 * NULL at "pExtensions".
307 *
308 * Note that the List returned by this function is immutable.
309 *
310 * PARAMETERS:
311 * "checker"
312 * Address of CertChainChecker whose supported extension OIDs are to be
313 * stored. Must be non-NULL.
314 * "pExtensions"
315 * Address where object pointer will be stored. Must be non-NULL.
316 * "plContext"
317 * Platform-specific context pointer.
318 * THREAD SAFETY:
319 * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
320 * RETURNS:
321 * Returns NULL if the function succeeds.
322 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
323 * Returns a Fatal Error if the function fails in an unrecoverable way.
324 */
325 PKIX_Error *
326 PKIX_CertChainChecker_GetSupportedExtensions(
327 PKIX_CertChainChecker *checker,
328 PKIX_List **pExtensions, /* list of PKIX_PL_OID */
329 void *plContext);
330
331 /*
332 * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState
333 * DESCRIPTION:
334 *
335 * Retrieves a pointer to a PKIX_PL_Object representing the internal state
336 * (if any) of the CertChainChecker pointed to by "checker" and stores it at
337 * "pCertChainCheckerState".
338 *
339 * PARAMETERS:
340 * "checker"
341 * Address of CertChainChecker whose state is to be stored.
342 * Must be non-NULL.
343 * "pCertChainCheckerState"
344 * Address where object pointer will be stored. Must be non-NULL.
345 * "plContext"
346 * Platform-specific context pointer.
347 * THREAD SAFETY:
348 * Conditionally Thread Safe
349 * (see Thread Safety Definitions in Programmer's Guide)
350 * RETURNS:
351 * Returns NULL if the function succeeds.
352 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
353 * Returns a Fatal Error if the function fails in an unrecoverable way.
354 */
355 PKIX_Error *
356 PKIX_CertChainChecker_GetCertChainCheckerState(
357 PKIX_CertChainChecker *checker,
358 PKIX_PL_Object **pCertChainCheckerState,
359 void *plContext);
360
361 /*
362 * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState
363 * DESCRIPTION:
364 *
365 * Sets the internal state of the CertChainChecker pointed to by "checker"
366 * using the Object pointed to by "certChainCheckerState". If "checker" needs
367 * a NULL internal state, "certChainCheckerState" should be set to NULL.
368 *
369 * PARAMETERS:
370 * "checker"
371 * Address of CertChainChecker whose state is to be set. Must be non-NULL.
372 * "certChainCheckerState"
373 * Address of Object representing internal state.
374 * "plContext"
375 * Platform-specific context pointer.
376 * THREAD SAFETY:
377 * Not Thread Safe - assumes exclusive access to "checker"
378 * (see Thread Safety Definitions in Programmer's Guide)
379 * RETURNS:
380 * Returns NULL if the function succeeds.
381 * Returns a CertChainChecker Error if the function fails in a non-fatal way.
382 * Returns a Fatal Error if the function fails in an unrecoverable way.
383 */
384 PKIX_Error *
385 PKIX_CertChainChecker_SetCertChainCheckerState(
386 PKIX_CertChainChecker *checker,
387 PKIX_PL_Object *certChainCheckerState,
388 void *plContext);
389
390 #ifdef __cplusplus
391 }
392 #endif
393
394 #endif /* _PKIX_CHECKER_H */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial