summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/libpkix/include/pkix_checker.h
blob: 97e29a8403a236adac3cb9d3459a99d58e4ebd21 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
/* 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_CertChainChecker type.
 *
 */

#ifndef _PKIX_CHECKER_H
#define _PKIX_CHECKER_H

#include "pkixt.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_CertChainChecker
 *
 * PKIX_CertChainCheckers provide a standard way for the caller to insert their
 * own custom checks to validate certificates. This may be useful in many
 * scenarios, including when the caller wishes to validate private certificate
 * extensions. The CheckCallback allows custom certificate processing to take
 * place. Additionally, a CertChainChecker can optionally maintain state
 * between successive calls to the CheckCallback. This certChainCheckerState
 * must be an Object (although any object type), allowing it to be
 * reference-counted and allowing it to provide the standard Object functions
 * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes
 * their CertChainChecker to be used during chain building, their
 * certChainCheckerState object must implement an appropriate Duplicate
 * function. The builder uses this Duplicate function when backtracking.
 *
 * Once the caller has created a CertChainChecker object, the caller then
 * specifies a CertChainChecker object in a ProcessingParams object
 * and passes the ProcessingParams object to PKIX_ValidateChain or
 * PKIX_BuildChain, which uses the objects to call the user's callback
 * functions as needed during the validation or building process.
 *
 * A CertChainChecker may be presented certificates in the "reverse" direction
 * (from trust anchor to target) or in the "forward" direction (from target to
 * trust anchor). All CertChainCheckers must support "reverse checking", while
 * support for "forward checking" is optional, but recommended. If "forward
 * checking" is not supported, building chains may be much less efficient. The
 * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to
 * determine whether forward checking is supported, and the
 * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to
 * determine whether the CertChainChecker has been initialized to expect the
 * certificates to be presented in the "forward" direction.
 */

/*
 * FUNCTION: PKIX_CertChainChecker_CheckCallback
 * DESCRIPTION:
 *
 *  This callback function checks whether the specified Cert pointed to by
 *  "cert" is valid using "checker's" internal certChainCheckerState (if any)
 *  and removes the critical extensions that it processes (if any) from the
 *  List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions".
 *  If the checker finds that the certificate is not valid, an Error pointer is
 *  returned.
 *
 *  If the checker uses non-blocking I/O, the address of a platform-dependent
 *  non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext",
 *  which the caller may use, in a platform-dependent way, to wait, poll, or
 *  otherwise determine when to try again. If the checker does not use
 *  non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL
 *  value was stored, on a subsequent call the checker will attempt to complete
 *  the pending I/O and, if successful, NULL will be stored at "pNBIOContext".
 *
 * PARAMETERS:
 *  "checker"
 *      Address of CertChainChecker whose certChainCheckerState and
 *      CheckCallback logic is to be used. Must be non-NULL.
 *  "cert"
 *      Address of Cert that is to be validated using "checker".
 *      Must be non-NULL.
 *  "unresolvedCriticalExtensions"
 *      Address of List of OIDs that represents the critical certificate
 *      extensions that have yet to be resolved. This parameter may be
 *      modified during the function call. Must be non-NULL.
 *  "pNBIOContext"
 *      Address at which is stored a platform-dependent structure indicating
 *      whether checking was suspended for non-blocking I/O. 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 object.
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
typedef PKIX_Error *
(*PKIX_CertChainChecker_CheckCallback)(
        PKIX_CertChainChecker *checker,
        PKIX_PL_Cert *cert,
        PKIX_List *unresolvedCriticalExtensions,  /* list of PKIX_PL_OID */
        void **pNBIOContext,
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_Create
 * DESCRIPTION:
 *
 *  Creates a new CertChainChecker and stores it at "pChecker". The new
 *  CertChainChecker uses the CheckCallback pointed to by "callback" as its
 *  callback function. It uses the Object pointed to by "initialState" (if
 *  any) as its initial state. As noted above, the initial state Object must
 *  provide a custom implementation of PKIX_PL_Object_Duplicate if the
 *  CertChainChecker is to be used during certificate chain building.
 *
 *  A CertChainChecker may be presented certificates in the "reverse"
 *  direction (from trust anchor to target) or in the "forward" direction
 *  (from target to trust anchor). All CertChainCheckers must support
 *  "reverse checking", while support for "forward checking" is optional. The
 *  CertChainChecker is initialized with two Boolean flags that deal with this
 *  distinction: "forwardCheckingSupported" and "forwardDirectionExpected".
 *  If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that
 *  this CertChainChecker is capable of checking certificates in the "forward"
 *  direction (as well as the "reverse" direction, which all CertChainCheckers
 *  MUST support). The "forwardDirectionExpected" Boolean flag indicates in
 *  which direction the CertChainChecker should expect the certificates to be
 *  presented. This is particularly useful for CertChainCheckers that are
 *  capable of checking in either the "forward" direction or the "reverse"
 *  direction, but have different processing steps depending on the direction.
 *
 *  The CertChainChecker also uses the List of OIDs pointed to by "extensions"
 *  as the supported certificate extensions. All certificate extensions that
 *  the CertChainChecker might possibly recognize and be able to process
 *  should be included in the List of supported extensions. If "checker" does
 *  not recognize or process any certificate extensions, "extensions" should
 *  be set to NULL.
 *
 * PARAMETERS:
 *  "callback"
 *      The CheckCallback function to be used. Must be non-NULL.
 *  "forwardCheckingSupported"
 *      A Boolean value indicating whether or not this CertChainChecker is
 *      capable of checking certificates in the "forward" direction.
 *  "forwardDirectionExpected"
 *      A Boolean value indicating whether or not this CertChainChecker should
 *      be used to check in the "forward" direction.
 *  "extensions"
 *      Address of List of OIDs representing the supported extensions.
 *  "initialState"
 *      Address of Object representing the CertChainChecker's initial state
 *      (if any).
 *  "pChecker"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_Create(
    PKIX_CertChainChecker_CheckCallback callback,
    PKIX_Boolean forwardCheckingSupported,
    PKIX_Boolean forwardDirectionExpected,
    PKIX_List *extensions,  /* list of PKIX_PL_OID */
    PKIX_PL_Object *initialState,
    PKIX_CertChainChecker **pChecker,
    void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_GetCheckCallback
 * DESCRIPTION:
 *
 *  Retrieves a pointer to "checker's" Check callback function and puts it in
 *  "pCallback".
 *
 * PARAMETERS:
 *  "checker"
 *      The CertChainChecker whose Check callback is desired. Must be non-NULL.
 *  "pCallback"
 *      Address where Check callback function pointer will be stored.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_GetCheckCallback(
        PKIX_CertChainChecker *checker,
        PKIX_CertChainChecker_CheckCallback *pCallback,
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported
 * DESCRIPTION:
 *
 *  Checks whether forward checking is supported by the CertChainChecker
 *  pointed to by "checker" and stores the Boolean result at
 *  "pForwardCheckingSupported".
 *
 *  A CertChainChecker may be presented certificates in the "reverse"
 *  direction (from trust anchor to target) or in the "forward" direction
 *  (from target to trust anchor). All CertChainCheckers must support
 *  "reverse checking", while support for "forward checking" is optional. This
 *  function is used to determine whether forward checking is supported.
 *
 * PARAMETERS:
 *  "checker"
 *      The CertChainChecker whose ability to validate certificates in the
 *      "forward" direction is to be checked. Must be non-NULL.
 *  "pForwardCheckingSupported"
 *      Destination of the Boolean result. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_IsForwardCheckingSupported(
        PKIX_CertChainChecker *checker,
        PKIX_Boolean *pForwardCheckingSupported,
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected
 * DESCRIPTION:
 *
 *  Checks whether the CertChainChecker pointed to by "checker" has been
 *  initialized to expect the certificates to be presented in the "forward"
 *  direction and stores the Boolean result at "pForwardDirectionExpected".
 *
 *  A CertChainChecker may be presented certificates in the "reverse"
 *  direction (from trust anchor to target) or in the "forward" direction
 *  (from target to trust anchor). All CertChainCheckers must support
 *  "reverse checking", while support for "forward checking" is optional. This
 *  function is used to determine in which direction the CertChainChecker
 *  expects the certificates to be presented.
 *
 * PARAMETERS:
 *  "checker"
 *      The CertChainChecker that has been initialized to expect certificates
 *      in either the "forward" or "reverse" directions. Must be non-NULL.
 *  "pForwardDirectionExpected"
 *      Destination of the Boolean result. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_IsForwardDirectionExpected(
        PKIX_CertChainChecker *checker,
        PKIX_Boolean *pForwardDirectionExpected,
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a List of OIDs (each OID corresponding to a
 *  certificate extension supported by the CertChainChecker pointed to by
 *  "checker") and stores it at "pExtensions". All certificate extensions that
 *  the CertChainChecker might possibly recognize and be able to process
 *  should be included in the List of supported extensions. If "checker" does
 *  not recognize or process any certificate extensions, this function stores
 *  NULL at "pExtensions".
 *
 *  Note that the List returned by this function is immutable.
 *
 * PARAMETERS:
 *  "checker"
 *      Address of CertChainChecker whose supported extension OIDs are to be
 *      stored. Must be non-NULL.
 *  "pExtensions"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_GetSupportedExtensions(
        PKIX_CertChainChecker *checker,
        PKIX_List **pExtensions, /* list of PKIX_PL_OID */
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a PKIX_PL_Object representing the internal state
 *  (if any) of the CertChainChecker pointed to by "checker" and stores it at
 *  "pCertChainCheckerState".
 *
 * PARAMETERS:
 *  "checker"
 *      Address of CertChainChecker whose state is to be stored.
 *      Must be non-NULL.
 *  "pCertChainCheckerState"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Conditionally Thread Safe
 *      (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_GetCertChainCheckerState(
        PKIX_CertChainChecker *checker,
        PKIX_PL_Object **pCertChainCheckerState,
        void *plContext);

/*
 * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState
 * DESCRIPTION:
 *
 *  Sets the internal state of the CertChainChecker pointed to by "checker"
 *  using the Object pointed to by "certChainCheckerState". If "checker" needs
 *  a NULL internal state, "certChainCheckerState" should be set to NULL.
 *
 * PARAMETERS:
 *  "checker"
 *      Address of CertChainChecker whose state is to be set. Must be non-NULL.
 *  "certChainCheckerState"
 *      Address of Object representing internal state.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Not Thread Safe - assumes exclusive access to "checker"
 *  (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CertChainChecker 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_CertChainChecker_SetCertChainCheckerState(
        PKIX_CertChainChecker *checker,
        PKIX_PL_Object *certChainCheckerState,
        void *plContext);

#ifdef __cplusplus
}
#endif

#endif /* _PKIX_CHECKER_H */