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