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 various parameters used
6  * by the top-level functions.
7  *
8  */
9 
10 #ifndef _PKIX_PARAMS_H
11 #define _PKIX_PARAMS_H
12 
13 #include "pkixt.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /* General
20  *
21  * Please refer to the libpkix Programmer's Guide for detailed information
22  * about how to use the libpkix library. Certain key warnings and notices from
23  * that document are repeated here for emphasis.
24  *
25  * All identifiers in this file (and all public identifiers defined in
26  * libpkix) begin with "PKIX_". Private identifiers only intended for use
27  * within the library begin with "pkix_".
28  *
29  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
30  *
31  * Unless otherwise noted, for all accessor (gettor) functions that return a
32  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
33  * shared object. Therefore, the caller should treat this shared object as
34  * read-only and should not modify this shared object. When done using the
35  * shared object, the caller should release the reference to the object by
36  * using the PKIX_PL_Object_DecRef function.
37  *
38  * While a function is executing, if its arguments (or anything referred to by
39  * its arguments) are modified, free'd, or destroyed, the function's behavior
40  * is undefined.
41  *
42  */
43 
44 /* PKIX_ProcessingParams
45  *
46  * PKIX_ProcessingParams are parameters used when validating or building a
47  * chain of certificates. Using the parameters, the caller can specify several
48  * things, including the various inputs to the PKIX chain validation
49  * algorithm (such as trust anchors, initial policies, etc), any customized
50  * functionality (such as CertChainCheckers, RevocationCheckers, CertStores),
51  * and whether revocation checking should be disabled.
52  *
53  * Once the caller has created the ProcessingParams object, the caller then
54  * passes it to PKIX_ValidateChain or PKIX_BuildChain, which uses it to call
55  * the user's callback functions as needed during the validation or building
56  * process.
57  *
58  * If a parameter is not set (or is set to NULL), it will be set to the
59  * default value for that parameter. The default value for the Date parameter
60  * is NULL, which indicates the current time when the path is validated. The
61  * default for the remaining parameters is the least constrained.
62  */
63 
64 /*
65  * FUNCTION: PKIX_ProcessingParams_Create
66  * DESCRIPTION:
67  *
68  *  Creates a new ProcessingParams object. Trust anchor list is set to
69  *  newly created empty list of trust. In this case trust anchors will
70  *  be taken from provided cert store. Pointed to the created
71  *  ProcessingParams object is stored in "pParams".
72  *
73  * PARAMETERS:
74  *  "anchors"
75  *      Address of List of (non-empty) TrustAnchors to be used.
76  *      Must be non-NULL.
77  *  "pParams"
78  *      Address where object pointer will be stored. Must be non-NULL.
79  *  "plContext"
80  *      Platform-specific context pointer.
81  * THREAD SAFETY:
82  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
83  * RETURNS:
84  *  Returns NULL if the function succeeds.
85  *  Returns a Params Error if the function fails in a non-fatal way.
86  *  Returns a Fatal Error if the function fails in an unrecoverable way.
87  */
88 PKIX_Error *
89 PKIX_ProcessingParams_Create(
90         PKIX_ProcessingParams **pParams,
91         void *plContext);
92 
93 /*
94  * FUNCTION: PKIX_ProcessingParams_GetCertChainCheckers
95  * DESCRIPTION:
96  *
97  *  Retrieves a pointer to the List of CertChainCheckers (if any) that are set
98  *  in the ProcessingParams pointed to by "params" and stores it at
99  *  "pCheckers". Each CertChainChecker represents a custom certificate
100  *  validation check used by PKIX_ValidateChain or PKIX_BuildChain as needed
101  *  during the validation or building process. If "params" does not have any
102  *  CertChainCheckers, this function stores an empty List at "pCheckers".
103  *
104  * PARAMETERS:
105  *  "params"
106  *      Address of ProcessingParams whose List of CertChainCheckers (if any)
107  *      are to be stored. Must be non-NULL.
108  *  "pCheckers"
109  *      Address where object pointer will be stored. Must be non-NULL.
110  *  "plContext"
111  *      Platform-specific context pointer.
112  * THREAD SAFETY:
113  *  Conditionally Thread Safe
114  *      (see Thread Safety Definitions in Programmer's Guide)
115  * RETURNS:
116  *  Returns NULL if the function succeeds.
117  *  Returns a Params Error if the function fails in a non-fatal way.
118  *  Returns a Fatal Error if the function fails in an unrecoverable way.
119  */
120 PKIX_Error *
121 PKIX_ProcessingParams_GetCertChainCheckers(
122         PKIX_ProcessingParams *params,
123         PKIX_List **pCheckers, /* list of PKIX_CertChainChecker */
124         void *plContext);
125 
126 /*
127  * FUNCTION: PKIX_ProcessingParams_SetCertChainCheckers
128  * DESCRIPTION:
129  *
130  *  Sets the ProcessingParams pointed to by "params" with a List of
131  *  CertChainCheckers pointed to by "checkers". Each CertChainChecker
132  *  represents a custom certificate validation check used by
133  *  PKIX_ValidateChain or PKIX_BuildChain as needed during the validation or
134  *  building process. If "checkers" is NULL, no CertChainCheckers will be used.
135  *
136  * PARAMETERS:
137  *  "params"
138  *      Address of ProcessingParams whose List of CertChainCheckers is to be
139  *      set. Must be non-NULL.
140  *  "checkers"
141  *      Address of List of CertChainCheckers to be set. If NULL, no
142  *      CertChainCheckers will be used.
143  *  "plContext"
144  *      Platform-specific context pointer.
145  * THREAD SAFETY:
146  *  Not Thread Safe - assumes exclusive access to "params" and "checkers"
147  *  (see Thread Safety Definitions in Programmer's Guide)
148  * RETURNS:
149  *  Returns NULL if the function succeeds.
150  *  Returns a Params Error if the function fails in a non-fatal way.
151  *  Returns a Fatal Error if the function fails in an unrecoverable way.
152  */
153 PKIX_Error *
154 PKIX_ProcessingParams_SetCertChainCheckers(
155         PKIX_ProcessingParams *params,
156         PKIX_List *checkers,  /* list of PKIX_CertChainChecker */
157         void *plContext);
158 
159 /*
160  * FUNCTION: PKIX_ProcessingParams_AddCertChainChecker
161  * DESCRIPTION:
162  *
163  *  Adds the CertChainChecker pointed to by "checker" to the ProcessingParams
164  *  pointed to by "params". The CertChainChecker represents a custom
165  *  certificate validation check used by PKIX_ValidateChain or PKIX_BuildChain
166  *  as needed during the validation or building process.
167  *
168  * PARAMETERS:
169  *  "params"
170  *      Address of ProcessingParams to be added to. Must be non-NULL.
171  *  "checker"
172  *      Address of CertChainChecker to be added. Must be non-NULL.
173  *  "plContext"
174  *      Platform-specific context pointer.
175  * THREAD SAFETY:
176  *  Not Thread Safe - assumes exclusive access to "params"
177  *  (see Thread Safety Definitions in Programmer's Guide)
178  * RETURNS:
179  *  Returns NULL if the function succeeds.
180  *  Returns a Params Error if the function fails in a non-fatal way.
181  *  Returns a Fatal Error if the function fails in an unrecoverable way.
182  */
183 PKIX_Error *
184 PKIX_ProcessingParams_AddCertChainChecker(
185         PKIX_ProcessingParams *params,
186         PKIX_CertChainChecker *checker,
187         void *plContext);
188 
189 /*
190  * FUNCTION: PKIX_ProcessingParams_GetRevocationChecker
191  * DESCRIPTION:
192  *
193  *  Retrieves a pointer to the RevocationChecker that are set
194  *  in the ProcessingParams pointed to by "params" and stores it at
195  *  "pRevChecker". Each RevocationChecker represents a revocation
196  *  check used by PKIX_ValidateChain or PKIX_BuildChain as needed during the
197  *  validation or building process. If "params" does not have any
198  *  RevocationCheckers, this function stores an empty List at "pRevChecker".
199  *
200  * PARAMETERS:
201  *  "params"
202  *      Address of ProcessingParams whose List of RevocationCheckers
203  *      is to be stored. Must be non-NULL.
204  *  "pRevChecker"
205  *      Address where object pointer will be stored. Must be non-NULL.
206  *  "plContext"
207  *      Platform-specific context pointer.
208  * THREAD SAFETY:
209  *  Conditionally Thread Safe
210  *      (see Thread Safety Definitions in Programmer's Guide)
211  * RETURNS:
212  *  Returns NULL if the function succeeds.
213  *  Returns a Params Error if the function fails in a non-fatal way.
214  *  Returns a Fatal Error if the function fails in an unrecoverable way.
215  */
216 PKIX_Error *
217 PKIX_ProcessingParams_GetRevocationChecker(
218         PKIX_ProcessingParams *params,
219         PKIX_RevocationChecker **pChecker,
220         void *plContext);
221 
222 /*
223  * FUNCTION: PKIX_ProcessingParams_SetRevocationChecker
224  * DESCRIPTION:
225  *
226  *  Sets the ProcessingParams pointed to by "params" with a
227  *  RevocationChecker pointed to by "revChecker". Revocation
228  *  checker object should be created and assigned to processing
229  *  parameters before chain build or validation can begin.
230  *
231  * PARAMETERS:
232  *  "params"
233  *      Address of ProcessingParams whose List of RevocationCheckers is to be
234  *      set. Must be non-NULL.
235  *  "revChecker"
236  *      Address of RevocationChecker to be set. Must be set before chain
237  *      building or validation.
238  *  "plContext"
239  *      Platform-specific context pointer.
240  * THREAD SAFETY:
241  *  Not Thread Safe - assumes exclusive access to "params"
242  *  (see Thread Safety Definitions in Programmer's Guide)
243  * RETURNS:
244  *  Returns NULL if the function succeeds.
245  *  Returns a Params Error if the function fails in a non-fatal way.
246  *  Returns a Fatal Error if the function fails in an unrecoverable way.
247  */
248 PKIX_Error *
249 PKIX_ProcessingParams_SetRevocationChecker(
250         PKIX_ProcessingParams *params,
251         PKIX_RevocationChecker *revChecker,
252         void *plContext);
253 
254 /*
255  * FUNCTION: PKIX_ProcessingParams_GetCertStores
256  * DESCRIPTION:
257  *
258  *  Retrieves a pointer to the List of CertStores (if any) that are set in the
259  *  ProcessingParams pointed to by "params" and stores it at "pStores". Each
260  *  CertStore represents a particular repository from which certificates and
261  *  CRLs can be retrieved by PKIX_ValidateChain or PKIX_BuildChain as needed
262  *  during the validation or building process. If "params" does not have any
263  *  CertStores, this function stores an empty List at "pStores".
264  *
265  * PARAMETERS:
266  *  "params"
267  *      Address of ProcessingParams whose List of CertStores (if any) are to
268  *      be stored. Must be non-NULL.
269  *  "pStores"
270  *      Address where object pointer will be stored. Must be non-NULL.
271  *  "plContext"
272  *      Platform-specific context pointer.
273  * THREAD SAFETY:
274  *  Conditionally Thread Safe
275  *      (see Thread Safety Definitions in Programmer's Guide)
276  * RETURNS:
277  *  Returns NULL if the function succeeds.
278  *  Returns a Params Error if the function fails in a non-fatal way.
279  *  Returns a Fatal Error if the function fails in an unrecoverable way.
280  */
281 PKIX_Error *
282 PKIX_ProcessingParams_GetCertStores(
283         PKIX_ProcessingParams *params,
284         PKIX_List **pStores,  /* list of PKIX_CertStore */
285         void *plContext);
286 
287 /*
288  * FUNCTION: PKIX_ProcessingParams_SetCertStores
289  * DESCRIPTION:
290  *
291  *  Sets the ProcessingParams pointed to by "params" with a List of CertStores
292  *  pointed to by "stores". Each CertStore represents a particular repository
293  *  from which certificates and CRLs can be retrieved by PKIX_ValidateChain or
294  *  PKIX_BuildChain as needed during the validation or building process. If
295  *  "stores" is NULL, no CertStores will be used.
296  *
297  * PARAMETERS:
298  *  "params"
299  *      Address of ProcessingParams whose List of CertStores is to be set.
300  *      Must be non-NULL.
301  *  "stores"
302  *      Address of List of CertStores to be set. If NULL, no CertStores will
303  *      be used.
304  *  "plContext"
305  *      Platform-specific context pointer.
306  * THREAD SAFETY:
307  *  Not Thread Safe - assumes exclusive access to "params"
308  *  (see Thread Safety Definitions in Programmer's Guide)
309  * RETURNS:
310  *  Returns NULL if the function succeeds.
311  *  Returns a Params Error if the function fails in a non-fatal way.
312  *  Returns a Fatal Error if the function fails in an unrecoverable way.
313  */
314 PKIX_Error *
315 PKIX_ProcessingParams_SetCertStores(
316         PKIX_ProcessingParams *params,
317         PKIX_List *stores,  /* list of PKIX_CertStore */
318         void *plContext);
319 
320 /*
321  * FUNCTION: PKIX_ProcessingParams_AddCertStore
322  * DESCRIPTION:
323  *
324  *  Adds the CertStore pointed to by "store" to the ProcessingParams pointed
325  *  to by "params". The CertStore represents a particular repository from
326  *  which certificates and CRLs can be retrieved by PKIX_ValidateChain or
327  *  PKIX_BuildChain as needed during the validation or building process.
328  *
329  * PARAMETERS:
330  *  "params"
331  *      Address of ProcessingParams to be added to. Must be non-NULL.
332  *  "store"
333  *      Address of CertStore to be added.
334  *  "plContext"
335  *      Platform-specific context pointer.
336  * THREAD SAFETY:
337  *  Not Thread Safe - assumes exclusive access to "params"
338  *  (see Thread Safety Definitions in Programmer's Guide)
339  * RETURNS:
340  *  Returns NULL if the function succeeds.
341  *  Returns a Params Error if the function fails in a non-fatal way.
342  *  Returns a Fatal Error if the function fails in an unrecoverable way.
343  */
344 PKIX_Error *
345 PKIX_ProcessingParams_AddCertStore(
346         PKIX_ProcessingParams *params,
347         PKIX_CertStore *store,
348         void *plContext);
349 
350 /*
351  * FUNCTION: PKIX_ProcessingParams_GetDate
352  * DESCRIPTION:
353  *
354  *  Retrieves a pointer to the Date (if any) that is set in the
355  *  ProcessingParams pointed to by "params" and stores it at "pDate". The
356  *  Date represents the time for which the validation of the certificate chain
357  *  should be determined. If "params" does not have any Date set, this function
358  *  stores NULL at "pDate".
359  *
360  * PARAMETERS:
361  *  "params"
362  *      Address of ProcessingParams whose Date (if any) is to be stored.
363  *      Must be non-NULL.
364  *  "pDate"
365  *      Address where object pointer will be stored. Must be non-NULL.
366  *  "plContext"
367  *      Platform-specific context pointer.
368  * THREAD SAFETY:
369  *  Conditionally Thread Safe
370  *      (see Thread Safety Definitions in Programmer's Guide)
371  * RETURNS:
372  *  Returns NULL if the function succeeds.
373  *  Returns a Params Error if the function fails in a non-fatal way.
374  *  Returns a Fatal Error if the function fails in an unrecoverable way.
375  */
376 PKIX_Error *
377 PKIX_ProcessingParams_GetDate(
378         PKIX_ProcessingParams *params,
379         PKIX_PL_Date **pDate,
380         void *plContext);
381 
382 /*
383  * FUNCTION: PKIX_ProcessingParams_SetDate
384  * DESCRIPTION:
385  *
386  *  Sets the ProcessingParams pointed to by "params" with a Date pointed to by
387  *  "date". The Date represents the time for which the validation of the
388  *  certificate chain should be determined. If "date" is NULL, the current
389  *  time is used during validation.
390  *
391  * PARAMETERS:
392  *  "params"
393  *      Address of ProcessingParams whose Date is to be set. Must be non-NULL.
394  *  "date"
395  *      Address of Date to be set. If NULL, current time is used.
396  *  "plContext"
397  *      Platform-specific context pointer.
398  * THREAD SAFETY:
399  *  Not Thread Safe - assumes exclusive access to "params"
400  *  (see Thread Safety Definitions in Programmer's Guide)
401  * RETURNS:
402  *  Returns NULL if the function succeeds.
403  *  Returns a Params Error if the function fails in a non-fatal way.
404  *  Returns a Fatal Error if the function fails in an unrecoverable way.
405  */
406 PKIX_Error *
407 PKIX_ProcessingParams_SetDate(
408         PKIX_ProcessingParams *params,
409         PKIX_PL_Date *date,
410         void *plContext);
411 
412 /*
413  * FUNCTION: PKIX_ProcessingParams_GetInitialPolicies
414  * DESCRIPTION:
415  *
416  *  Retrieves a pointer to the List of OIDs (if any) that are set in the
417  *  ProcessingParams pointed to by "params" and stores it at "pInitPolicies".
418  *  Each OID represents an initial policy identifier, indicating that any
419  *  one of these policies would be acceptable to the certificate user for
420  *  the purposes of certification path processing. If "params" does not have
421  *  any initial policies, this function stores an empty List at
422  *  "pInitPolicies".
423  *
424  * PARAMETERS:
425  *  "params"
426  *      Address of ProcessingParams whose List of OIDs (if any) are to be
427  *      stored. Must be non-NULL.
428  *  "pInitPolicies"
429  *      Address where object pointer will be stored. Must be non-NULL.
430  *  "plContext"
431  *      Platform-specific context pointer.
432  * THREAD SAFETY:
433  *  Conditionally Thread Safe
434  *      (see Thread Safety Definitions in Programmer's Guide)
435  * RETURNS:
436  *  Returns NULL if the function succeeds.
437  *  Returns a Params Error if the function fails in a non-fatal way.
438  *  Returns a Fatal Error if the function fails in an unrecoverable way.
439  */
440 PKIX_Error *
441 PKIX_ProcessingParams_GetInitialPolicies(
442         PKIX_ProcessingParams *params,
443         PKIX_List **pInitPolicies,    /* list of PKIX_PL_OID */
444         void *plContext);
445 
446 /*
447  * FUNCTION: PKIX_ProcessingParams_SetInitialPolicies
448  * DESCRIPTION:
449  *
450  *  Sets the ProcessingParams pointed to by "params" with a List of OIDs
451  *  pointed to by "initPolicies".
452  *
453  *  Each OID represents an initial policy identifier, indicating that any
454  *  one of these policies would be acceptable to the certificate user for
455  *  the purposes of certification path processing. By default, any policy
456  *  is acceptable (i.e. all policies), so a user that wants to allow any
457  *  policy as acceptable does not need to call this method. Similarly, if
458  *  initPolicies is NULL or points to an empty List, all policies are
459  *  acceptable.
460  *
461  * PARAMETERS:
462  *  "params"
463  *      Address of ProcessingParams whose List of OIDs is to be set.
464  *      Must be non-NULL.
465  *  "initPolicies"
466  *      Address of List of OIDs to be set. If NULL or if pointing to an empty
467  *      List, all policies are acceptable.
468  *  "plContext"
469  *      Platform-specific context pointer.
470  * THREAD SAFETY:
471  *  Not Thread Safe - assumes exclusive access to "params"
472  *  (see Thread Safety Definitions in Programmer's Guide)
473  * RETURNS:
474  *  Returns NULL if the function succeeds.
475  *  Returns a Params Error if the function fails in a non-fatal way.
476  *  Returns a Fatal Error if the function fails in an unrecoverable way.
477  */
478 PKIX_Error *
479 PKIX_ProcessingParams_SetInitialPolicies(
480         PKIX_ProcessingParams *params,
481         PKIX_List *initPolicies,    /* list of PKIX_PL_OID */
482         void *plContext);
483 
484 /*
485  * FUNCTION: PKIX_ProcessingParams_GetPolicyQualifiersRejected
486  * DESCRIPTION:
487  *
488  *  Checks whether the ProcessingParams pointed to by "params" indicate that
489  *  policy qualifiers should be rejected and stores the Boolean result at
490  *  "pRejected".
491  *
492  * PARAMETERS:
493  *  "params"
494  *      Address of ProcessingParams used to determine whether or not policy
495  *      qualifiers should be rejected. Must be non-NULL.
496  *  "pRejected"
497  *      Address where Boolean will be stored. Must be non-NULL.
498  *  "plContext"
499  *      Platform-specific context pointer.
500  * THREAD SAFETY:
501  *  Conditionally Thread Safe
502  *      (see Thread Safety Definitions in Programmer's Guide)
503  * RETURNS:
504  *  Returns NULL if the function succeeds.
505  *  Returns a Params Error if the function fails in a non-fatal way.
506  *  Returns a Fatal Error if the function fails in an unrecoverable way.
507  */
508 PKIX_Error *
509 PKIX_ProcessingParams_GetPolicyQualifiersRejected(
510         PKIX_ProcessingParams *params,
511         PKIX_Boolean *pRejected,
512         void *plContext);
513 
514 /*
515  * FUNCTION: PKIX_ProcessingParams_SetPolicyQualifiersRejected
516  * DESCRIPTION:
517  *
518  *  Specifies in the ProcessingParams pointed to by "params" whether policy
519  *  qualifiers are rejected using the Boolean value of "rejected".
520  *
521  * PARAMETERS:
522  *  "params"
523  *      Address of ProcessingParams to be set. Must be non-NULL.
524  *  "rejected"
525  *      Boolean value indicating whether policy qualifiers are to be rejected.
526  *  "plContext"
527  *      Platform-specific context pointer.
528  * THREAD SAFETY:
529  *  Not Thread Safe - assumes exclusive access to "params"
530  *  (see Thread Safety Definitions in Programmer's Guide)
531  * RETURNS:
532  *  Returns NULL if the function succeeds.
533  *  Returns a Params Error if the function fails in a non-fatal way.
534  *  Returns a Fatal Error if the function fails in an unrecoverable way.
535  */
536 PKIX_Error *
537 PKIX_ProcessingParams_SetPolicyQualifiersRejected(
538         PKIX_ProcessingParams *params,
539         PKIX_Boolean rejected,
540         void *plContext);
541 
542 /*
543  * FUNCTION: PKIX_ProcessingParams_GetTargetCertConstraints
544  * DESCRIPTION:
545  *
546  *  Retrieves a pointer to the CertSelector (if any) that is set in the
547  *  ProcessingParams pointed to by "params" and stores it at "pConstraints".
548  *  The CertSelector represents the constraints to be placed on the target
549  *  certificate. If "params" does not have any CertSelector set, this function
550  *  stores NULL at "pConstraints".
551  *
552  * PARAMETERS:
553  *  "params"
554  *      Address of ProcessingParams whose CertSelector (if any) is to be
555  *      stored. Must be non-NULL.
556  *  "pConstraints"
557  *      Address where object pointer will be stored. Must be non-NULL.
558  *  "plContext"
559  *      Platform-specific context pointer.
560  * THREAD SAFETY:
561  *  Conditionally Thread Safe
562  *      (see Thread Safety Definitions in Programmer's Guide)
563  * RETURNS:
564  *  Returns NULL if the function succeeds.
565  *  Returns a Params Error if the function fails in a non-fatal way.
566  *  Returns a Fatal Error if the function fails in an unrecoverable way.
567  */
568 PKIX_Error *
569 PKIX_ProcessingParams_GetTargetCertConstraints(
570         PKIX_ProcessingParams *params,
571         PKIX_CertSelector **pConstraints,
572         void *plContext);
573 
574 /*
575  * FUNCTION: PKIX_ProcessingParams_SetTargetCertConstraints
576  * DESCRIPTION:
577  *
578  *  Sets the ProcessingParams pointed to by "params" with a CertSelector
579  *  pointed to by "constraints". The CertSelector represents the constraints
580  *  to be placed on the target certificate. If "constraints" is NULL, no
581  *  constraints are defined.
582  *
583  * PARAMETERS:
584  *  "params"
585  *      Address of ProcessingParams whose CertSelector is to be set.
586  *      Must be non-NULL.
587  *  "constraints"
588  *      Address of CertSelector to be set. If NULL, no constraints are defined.
589  *  "plContext"
590  *      Platform-specific context pointer.
591  * THREAD SAFETY:
592  *  Not Thread Safe - assumes exclusive access to "params"
593  *  (see Thread Safety Definitions in Programmer's Guide)
594  * RETURNS:
595  *  Returns NULL if the function succeeds.
596  *  Returns a Params Error if the function fails in a non-fatal way.
597  *  Returns a Fatal Error if the function fails in an unrecoverable way.
598  */
599 PKIX_Error *
600 PKIX_ProcessingParams_SetTargetCertConstraints(
601         PKIX_ProcessingParams *params,
602         PKIX_CertSelector *constraints,
603         void *plContext);
604 
605 /*
606  * FUNCTION: PKIX_ProcessingParams_GetTrustAnchors
607  * DESCRIPTION:
608  *
609  *  Retrieves a pointer to the List of TrustAnchors that are set in
610  *  the ProcessingParams pointed to by "params" and stores it at "pAnchors".
611  *  If the function succeeds, the pointer to the List is guaranteed to be
612  *  non-NULL and the List is guaranteed to be non-empty.
613  *
614  * PARAMETERS:
615  *  "params"
616  *      Address of ProcessingParams whose List of TrustAnchors are to
617  *      be stored. Must be non-NULL.
618  *  "pAnchors"
619  *      Address where object pointer will be stored. Must be non-NULL.
620  *  "plContext"
621  *      Platform-specific context pointer.
622  * THREAD SAFETY:
623  *  Conditionally Thread Safe
624  *      (see Thread Safety Definitions in Programmer's Guide)
625  * RETURNS:
626  *  Returns NULL if the function succeeds.
627  *  Returns a Params Error if the function fails in a non-fatal way.
628  *  Returns a Fatal Error if the function fails in an unrecoverable way.
629  */
630 PKIX_Error *
631 PKIX_ProcessingParams_GetTrustAnchors(
632         PKIX_ProcessingParams *params,
633         PKIX_List **pAnchors,  /* list of TrustAnchor */
634         void *plContext);
635 /*
636  * FUNCTION: PKIX_ProcessingParams_SetTrustAnchors
637  * DESCRIPTION:
638  *
639  * Sets user defined set of trust anchors. The handling of the trust anchors
640  * may be furthered alter via PKIX_ProcessingParams_SetUseOnlyTrustAnchors.
641  * By default, a certificate will be considered invalid if it does not chain
642  * to a trusted anchor from this list.
643  *
644  * PARAMETERS:
645  *  "params"
646  *      Address of ProcessingParams whose List of TrustAnchors are to
647  *      be stored. Must be non-NULL.
648  *  "anchors"
649  *      Address of the trust anchors list object. Must be non-NULL.
650  *  "plContext"
651  *      Platform-specific context pointer.
652  * THREAD SAFETY:
653  *  Conditionally Thread Safe
654  *      (see Thread Safety Definitions in Programmer's Guide)
655  * RETURNS:
656  *  Returns NULL if the function succeeds.
657  *  Returns a Params Error if the function fails in a non-fatal way.
658  *  Returns a Fatal Error if the function fails in an unrecoverable way.
659  */
660 PKIX_Error *
661 PKIX_ProcessingParams_SetTrustAnchors(
662         PKIX_ProcessingParams *params,
663         PKIX_List *pAnchors,  /* list of TrustAnchor */
664         void *plContext);
665 
666 /*
667  * FUNCTION: PKIX_ProcessingParams_GetUseOnlyTrustAnchors
668  * DESCRIPTION:
669  *
670  * Retrieves a pointer to the Boolean. The boolean value represents
671  * the switch value that is used to identify whether trust anchors, if
672  * specified, should be the exclusive source of trust information.
673  * If the function succeeds, the pointer to the Boolean is guaranteed to be
674  * non-NULL.
675  *
676  * PARAMETERS:
677  *  "params"
678  *      Address of ProcessingParams. Must be non-NULL.
679  *  "pUseOnlyTrustAnchors"
680  *      Address where object pointer will be stored. Must be non-NULL.
681  *  "plContext"
682  *      Platform-specific context pointer.
683  * THREAD SAFETY:
684  *  Conditionally Thread Safe
685  *      (see Thread Safety Definitions in Programmer's Guide)
686  * RETURNS:
687  *  Returns NULL if the function succeeds.
688  *  Returns a Params Error if the function fails in a non-fatal way.
689  *  Returns a Fatal Error if the function fails in an unrecoverable way.
690  */
691 PKIX_Error *
692 PKIX_ProcessingParams_GetUseOnlyTrustAnchors(
693         PKIX_ProcessingParams *params,
694         PKIX_Boolean *pUseOnlyTrustAnchors,
695         void *plContext);
696 
697 /*
698  * FUNCTION: PKIX_ProcessingParams_SetUseOnlyTrustAnchors
699  * DESCRIPTION:
700  *
701  * Configures whether trust anchors are used as the exclusive source of trust.
702  *
703  * PARAMETERS:
704  *  "params"
705  *      Address of ProcessingParams. Must be non-NULL.
706  *  "useOnlyTrustAnchors"
707  *      If true, indicates that trust anchors should be used exclusively when
708  *      they have been specified via PKIX_ProcessingParams_SetTrustAnchors. A
709  *      certificate will be considered invalid if it does not chain to a
710  *      trusted anchor from that list.
711  *      If false, indicates that the trust anchors are additive to whatever
712  *      existing trust stores are configured. A certificate is considered
713  *      valid if it chains to EITHER a trusted anchor from that list OR a
714  *      certificate marked trusted in a trust store.
715  *  "plContext"
716  *      Platform-specific context pointer.
717  * THREAD SAFETY:
718  *  Conditionally Thread Safe
719  *      (see Thread Safety Definitions in Programmer's Guide)
720  * RETURNS:
721  *  Returns NULL if the function succeeds.
722  *  Returns a Params Error if the function fails in a non-fatal way.
723  *  Returns a Fatal Error if the function fails in an unrecoverable way.
724  */
725 PKIX_Error *
726 PKIX_ProcessingParams_SetUseOnlyTrustAnchors(
727         PKIX_ProcessingParams *params,
728         PKIX_Boolean useOnlyTrustAnchors,
729         void *plContext);
730 
731 /*
732  * FUNCTION: PKIX_ProcessingParams_GetUseAIAForCertFetching
733  * DESCRIPTION:
734  *
735  *  Retrieves a pointer to the Boolean. The boolean value represents
736  *  the switch value that is used to identify if url in cert AIA extension
737  *  may be used for cert fetching.
738  *  If the function succeeds, the pointer to the Boolean is guaranteed to be
739  *  non-NULL.
740  *
741  * PARAMETERS:
742  *  "params"
743  *      Address of ProcessingParams. Must be non-NULL.
744  *  "pUseAIA"
745  *      Address where object pointer will be stored. Must be non-NULL.
746  *  "plContext"
747  *      Platform-specific context pointer.
748  * THREAD SAFETY:
749  *  Conditionally Thread Safe
750  *      (see Thread Safety Definitions in Programmer's Guide)
751  * RETURNS:
752  *  Returns NULL if the function succeeds.
753  *  Returns a Params Error if the function fails in a non-fatal way.
754  *  Returns a Fatal Error if the function fails in an unrecoverable way.
755  */
756 PKIX_Error *
757 PKIX_ProcessingParams_GetUseAIAForCertFetching(
758         PKIX_ProcessingParams *params,
759         PKIX_Boolean *pUseAIA,  /* list of TrustAnchor */
760         void *plContext);
761 /*
762  * FUNCTION: PKIX_ProcessingParams_SetTrustAnchors
763  * DESCRIPTION:
764  *
765  * Sets switch value that defines if url in cert AIA extension
766  * may be used for cert fetching.
767  *
768  * PARAMETERS:
769  *  "params"
770  *      Address of ProcessingParams.
771  *  "useAIA"
772  *      Address of the trust anchors list object. Must be non-NULL.
773  *  "plContext"
774  *      Platform-specific context pointer.
775  * THREAD SAFETY:
776  *  Conditionally Thread Safe
777  *      (see Thread Safety Definitions in Programmer's Guide)
778  * RETURNS:
779  *  Returns NULL if the function succeeds.
780  *  Returns a Params Error if the function fails in a non-fatal way.
781  *  Returns a Fatal Error if the function fails in an unrecoverable way.
782  */
783 PKIX_Error *
784 PKIX_ProcessingParams_SetUseAIAForCertFetching(
785         PKIX_ProcessingParams *params,
786         PKIX_Boolean useAIA,
787         void *plContext);
788 
789 /*
790  * FUNCTION: PKIX_ProcessingParams_SetQualifyTargetCert
791  * DESCRIPTION:
792  *
793  * Sets a boolean value that tells if libpkix needs to check that
794  * the target certificate satisfies the conditions set in processing
795  * parameters. Includes but not limited to date, ku and eku checks.
796  *
797  * PARAMETERS:
798  *  "params"
799  *      Address of ProcessingParams whose List of TrustAnchors are to
800  *      be stored. Must be non-NULL.
801  *  "qualifyTargetCert"
802  *      boolean value if set to true will trigger qualification of the
803  *      target certificate.
804  *  "plContext"
805  *      Platform-specific context pointer.
806  * THREAD SAFETY:
807  *  Conditionally Thread Safe
808  *      (see Thread Safety Definitions in Programmer's Guide)
809  * RETURNS:
810  *  Returns NULL if the function succeeds.
811  *  Returns a Params Error if the function fails in a non-fatal way.
812  *  Returns a Fatal Error if the function fails in an unrecoverable way.
813  */
814 PKIX_Error *
815 PKIX_ProcessingParams_SetQualifyTargetCert(
816         PKIX_ProcessingParams *params,
817         PKIX_Boolean qualifyTargetCert,
818         void *plContext);
819 
820 /*
821  * FUNCTION: PKIX_ProcessingParams_GetHintCerts
822  * DESCRIPTION:
823  *
824  *  Retrieves a pointer to a List of Certs supplied by the user as a suggested
825  *  partial CertChain (subject to verification), that are set in the
826  *  ProcessingParams pointed to by "params", and stores it at "pHintCerts".
827  *  The List returned may be empty or NULL.
828  *
829  * PARAMETERS:
830  *  "params"
831  *      Address of ProcessingParams whose List of TrustAnchors are to
832  *      be stored. Must be non-NULL.
833  *  "pHintCerts"
834  *      Address where object pointer will be stored. Must be non-NULL.
835  *  "plContext"
836  *      Platform-specific context pointer.
837  * THREAD SAFETY:
838  *  Conditionally Thread Safe
839  *      (see Thread Safety Definitions in Programmer's Guide)
840  * RETURNS:
841  *  Returns NULL if the function succeeds.
842  *  Returns a Params Error if the function fails in a non-fatal way.
843  *  Returns a Fatal Error if the function fails in an unrecoverable way.
844  */
845 PKIX_Error *
846 PKIX_ProcessingParams_GetHintCerts(
847         PKIX_ProcessingParams *params,
848         PKIX_List **pHintCerts,
849         void *plContext);
850 
851 /*
852  * FUNCTION: PKIX_ProcessingParams_SetHintCerts
853  * DESCRIPTION:
854  *
855  *  Stores a pointer to a List of Certs supplied by the user as a suggested
856  *  partial CertChain (subject to verification), as an element in the
857  *  ProcessingParams pointed to by "params". The List may be empty or NULL.
858  *
859  * PARAMETERS:
860  *  "params"
861  *      Address of ProcessingParams whose List of HintCerts is to be stored.
862  *      Must be non-NULL.
863  *  "hintCerts"
864  *      Address where object pointer will be stored. Must be non-NULL.
865  *  "plContext"
866  *      Platform-specific context pointer.
867  * THREAD SAFETY:
868  *  Conditionally Thread Safe
869  *      (see Thread Safety Definitions in Programmer's Guide)
870  * RETURNS:
871  *  Returns NULL if the function succeeds.
872  *  Returns a Params Error if the function fails in a non-fatal way.
873  *  Returns a Fatal Error if the function fails in an unrecoverable way.
874  */
875 PKIX_Error *
876 PKIX_ProcessingParams_SetHintCerts(
877         PKIX_ProcessingParams *params,
878         PKIX_List *hintCerts,
879         void *plContext);
880 
881 /*
882  * FUNCTION: PKIX_ProcessingParams_GetResourceLimits
883  * DESCRIPTION:
884  *
885  *  Retrieves a pointer to the ResourceLimits (if any) that is set in the
886  *  ProcessingParams pointed to by "params" and stores it at "pResourceLimits".
887  *  The ResourceLimits represent the maximum resource usage that the caller
888  *  desires (such as MaxTime). The ValidateChain or BuildChain call will not
889  *  exceed these maximum limits. If "params" does not have any ResourceLimits
890  *  set, this function stores NULL at "pResourceLimits".
891  *
892  * PARAMETERS:
893  *  "params"
894  *      Address of ProcessingParams whose ResourceLimits (if any) are to be
895  *      stored. Must be non-NULL.
896  *  "pResourceLimits"
897  *      Address where object pointer will be stored. Must be non-NULL.
898  *  "plContext"
899  *      Platform-specific context pointer.
900  * THREAD SAFETY:
901  *  Conditionally Thread Safe
902  *      (see Thread Safety Definitions in Programmer's Guide)
903  * RETURNS:
904  *  Returns NULL if the function succeeds.
905  *  Returns a Params Error if the function fails in a non-fatal way.
906  *  Returns a Fatal Error if the function fails in an unrecoverable way.
907  */
908 PKIX_Error *
909 PKIX_ProcessingParams_GetResourceLimits(
910         PKIX_ProcessingParams *params,
911         PKIX_ResourceLimits **pResourceLimits,
912         void *plContext);
913 
914 /*
915  * FUNCTION: PKIX_ProcessingParams_SetResourceLimits
916  * DESCRIPTION:
917  *
918  *  Sets the ProcessingParams pointed to by "params" with a ResourceLimits
919  *  object pointed to by "resourceLimits". The ResourceLimits represent the
920  *  maximum resource usage that the caller desires (such as MaxTime). The
921  *  ValidateChain or BuildChain call will not exceed these maximum limits.
922  *  If "resourceLimits" is NULL, no ResourceLimits are defined.
923  *
924  * PARAMETERS:
925  *  "params"
926  *      Address of ProcessingParams whose ResourceLimits are to be set.
927  *      Must be non-NULL.
928  *  "resourceLimits"
929  *      Address of ResourceLimits to be set. If NULL, no limits are defined.
930  *  "plContext"
931  *      Platform-specific context pointer.
932  * THREAD SAFETY:
933  *  Not Thread Safe - assumes exclusive access to "params"
934  *  (see Thread Safety Definitions in Programmer's Guide)
935  * RETURNS:
936  *  Returns NULL if the function succeeds.
937  *  Returns a Params Error if the function fails in a non-fatal way.
938  *  Returns a Fatal Error if the function fails in an unrecoverable way.
939  */
940 PKIX_Error *
941 PKIX_ProcessingParams_SetResourceLimits(
942         PKIX_ProcessingParams *params,
943         PKIX_ResourceLimits *resourceLimits,
944         void *plContext);
945 
946 /*
947  * FUNCTION: PKIX_ProcessingParams_IsAnyPolicyInhibited
948  * DESCRIPTION:
949  *
950  *  Checks whether the ProcessingParams pointed to by "params" indicate that
951  *  anyPolicy is inhibited and stores the Boolean result at "pInhibited".
952  *
953  * PARAMETERS:
954  *  "params"
955  *      Address of ProcessingParams used to determine whether or not anyPolicy
956  *      inhibited. Must be non-NULL.
957  *  "pInhibited"
958  *      Address where Boolean will be stored. Must be non-NULL.
959  *  "plContext"
960  *      Platform-specific context pointer.
961  * THREAD SAFETY:
962  *  Conditionally Thread Safe
963  *      (see Thread Safety Definitions in Programmer's Guide)
964  * RETURNS:
965  *  Returns NULL if the function succeeds.
966  *  Returns a Params Error if the function fails in a non-fatal way.
967  *  Returns a Fatal Error if the function fails in an unrecoverable way.
968  */
969 PKIX_Error *
970 PKIX_ProcessingParams_IsAnyPolicyInhibited(
971         PKIX_ProcessingParams *params,
972         PKIX_Boolean *pInhibited,
973         void *plContext);
974 
975 /*
976  * FUNCTION: PKIX_ProcessingParams_SetAnyPolicyInhibited
977  * DESCRIPTION:
978  *
979  *  Specifies in the ProcessingParams pointed to by "params" whether anyPolicy
980  *  is inhibited using the Boolean value of "inhibited".
981  *
982  * PARAMETERS:
983  *  "params"
984  *      Address of ProcessingParams to be set. Must be non-NULL.
985  *  "inhibited"
986  *      Boolean value indicating whether anyPolicy is to be inhibited.
987  *  "plContext"
988  *      Platform-specific context pointer.
989  * THREAD SAFETY:
990  *  Not Thread Safe - assumes exclusive access to "params"
991  *  (see Thread Safety Definitions in Programmer's Guide)
992  * RETURNS:
993  *  Returns NULL if the function succeeds.
994  *  Returns a Params Error if the function fails in a non-fatal way.
995  *  Returns a Fatal Error if the function fails in an unrecoverable way.
996  */
997 PKIX_Error *
998 PKIX_ProcessingParams_SetAnyPolicyInhibited(
999         PKIX_ProcessingParams *params,
1000         PKIX_Boolean inhibited,
1001         void *plContext);
1002 
1003 /*
1004  * FUNCTION: PKIX_ProcessingParams_IsExplicitPolicyRequired
1005  * DESCRIPTION:
1006  *
1007  *  Checks whether the ProcessingParams pointed to by "params" indicate that
1008  *  explicit policies are required and stores the Boolean result at
1009  *  "pRequired".
1010  *
1011  * PARAMETERS:
1012  *  "params"
1013  *      Address of ProcessingParams used to determine whether or not explicit
1014  *      policies are required. Must be non-NULL.
1015  *  "pRequired"
1016  *      Address where Boolean will be stored. Must be non-NULL.
1017  *  "plContext"
1018  *      Platform-specific context pointer.
1019  * THREAD SAFETY:
1020  *  Conditionally Thread Safe
1021  *      (see Thread Safety Definitions in Programmer's Guide)
1022  * RETURNS:
1023  *  Returns NULL if the function succeeds.
1024  *  Returns a Params Error if the function fails in a non-fatal way.
1025  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1026  */
1027 PKIX_Error *
1028 PKIX_ProcessingParams_IsExplicitPolicyRequired(
1029         PKIX_ProcessingParams *params,
1030         PKIX_Boolean *pRequired,
1031         void *plContext);
1032 
1033 /*
1034  * FUNCTION: PKIX_ProcessingParams_SetExplicitPolicyRequired
1035  * DESCRIPTION:
1036  *
1037  *  Specifies in the ProcessingParams pointed to by "params" whether explicit
1038  *  policies are required using the Boolean value of "required".
1039  *
1040  * PARAMETERS:
1041  *  "params"
1042  *      Address of ProcessingParams to be set. Must be non-NULL.
1043  *  "required"
1044  *      Boolean value indicating whether explicit policies are to be required.
1045  *  "plContext"
1046  *      Platform-specific context pointer.
1047  * THREAD SAFETY:
1048  *  Not Thread Safe - assumes exclusive access to "params"
1049  *  (see Thread Safety Definitions in Programmer's Guide)
1050  * RETURNS:
1051  *  Returns NULL if the function succeeds.
1052  *  Returns a Params Error if the function fails in a non-fatal way.
1053  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1054  */
1055 PKIX_Error *
1056 PKIX_ProcessingParams_SetExplicitPolicyRequired(
1057         PKIX_ProcessingParams *params,
1058         PKIX_Boolean required,
1059         void *plContext);
1060 
1061 /*
1062  * FUNCTION: PKIX_ProcessingParams_IsPolicyMappingInhibited
1063  * DESCRIPTION:
1064  *
1065  *  Checks whether the ProcessingParams pointed to by "params" indicate that
1066  *  policyMapping is inhibited and stores the Boolean result at "pInhibited".
1067  *
1068  * PARAMETERS:
1069  *  "params"
1070  *      Address of ProcessingParams used to determine whether or not policy
1071  *      mappings are inhibited. Must be non-NULL.
1072  *  "pInhibited"
1073  *      Address where Boolean will be stored. Must be non-NULL.
1074  *  "plContext"
1075  *      Platform-specific context pointer.
1076  * THREAD SAFETY:
1077  *  Conditionally Thread Safe
1078  *      (see Thread Safety Definitions in Programmer's Guide)
1079  * RETURNS:
1080  *  Returns NULL if the function succeeds.
1081  *  Returns a Params Error if the function fails in a non-fatal way.
1082  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1083  */
1084 PKIX_Error *
1085 PKIX_ProcessingParams_IsPolicyMappingInhibited(
1086         PKIX_ProcessingParams *params,
1087         PKIX_Boolean *pInhibited,
1088         void *plContext);
1089 
1090 /*
1091  * FUNCTION: PKIX_ProcessingParams_SetPolicyMappingInhibited
1092  * DESCRIPTION:
1093  *
1094  *  Specifies in the ProcessingParams pointed to by "params" whether policy
1095  *  mapping is inhibited using the Boolean value of "inhibited".
1096  *
1097  * PARAMETERS:
1098  *  "params"
1099  *      Address of ProcessingParams to be set. Must be non-NULL.
1100  *  "inhibited"
1101  *      Boolean value indicating whether policy mapping is to be inhibited.
1102  *  "plContext"
1103  *      Platform-specific context pointer.
1104  * THREAD SAFETY:
1105  *  Not Thread Safe - assumes exclusive access to "params"
1106  *  (see Thread Safety Definitions in Programmer's Guide)
1107  * RETURNS:
1108  *  Returns NULL if the function succeeds.
1109  *  Returns a Params Error if the function fails in a non-fatal way.
1110  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1111  */
1112 PKIX_Error *
1113 PKIX_ProcessingParams_SetPolicyMappingInhibited(
1114         PKIX_ProcessingParams *params,
1115         PKIX_Boolean inhibited,
1116         void *plContext);
1117 
1118 
1119 /* PKIX_ValidateParams
1120  *
1121  * PKIX_ValidateParams consists of a ProcessingParams object as well as the
1122  * List of Certs (certChain) that the caller is trying to validate.
1123  */
1124 
1125 /*
1126  * FUNCTION: PKIX_ValidateParams_Create
1127  * DESCRIPTION:
1128  *
1129  *  Creates a new ValidateParams object and stores it at "pParams".
1130  *
1131  * PARAMETERS:
1132  *  "procParams"
1133  *      Address of ProcessingParams to be used. Must be non-NULL.
1134  *  "chain"
1135  *      Address of List of Certs (certChain) to be validated. Must be non-NULL.
1136  *  "pParams"
1137  *      Address where object pointer will be stored. Must be non-NULL.
1138  *  "plContext"
1139  *      Platform-specific context pointer.
1140  * THREAD SAFETY:
1141  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1142  * RETURNS:
1143  *  Returns NULL if the function succeeds.
1144  *  Returns a Params Error if the function fails in a non-fatal way.
1145  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1146  */
1147 PKIX_Error *
1148 PKIX_ValidateParams_Create(
1149         PKIX_ProcessingParams *procParams,
1150         PKIX_List *chain,
1151         PKIX_ValidateParams **pParams,
1152         void *plContext);
1153 
1154 /*
1155  * FUNCTION: PKIX_ValidateParams_GetProcessingParams
1156  * DESCRIPTION:
1157  *
1158  *  Retrieves a pointer to the ProcessingParams that represent the basic
1159  *  certificate processing parameters used during chain validation and chain
1160  *  building from the ValidateParams pointed to by "valParams" and stores it
1161  *  at "pProcParams". If the function succeeds, the pointer to the
1162  *  ProcessingParams is guaranteed to be non-NULL.
1163  *
1164  * PARAMETERS:
1165  *  "valParams"
1166  *      Address of ValidateParams whose ProcessingParams are to be stored.
1167  *      Must be non-NULL.
1168  *  "pProcParams"
1169  *      Address where object pointer will be stored. Must be non-NULL.
1170  *  "plContext"
1171  *      Platform-specific context pointer.
1172  * THREAD SAFETY:
1173  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1174  * RETURNS:
1175  *  Returns NULL if the function succeeds.
1176  *  Returns a Params Error if the function fails in a non-fatal way.
1177  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1178  */
1179 PKIX_Error *
1180 PKIX_ValidateParams_GetProcessingParams(
1181         PKIX_ValidateParams *valParams,
1182         PKIX_ProcessingParams **pProcParams,
1183         void *plContext);
1184 
1185 /*
1186  * FUNCTION: PKIX_ValidateParams_GetCertChain
1187  * DESCRIPTION:
1188  *
1189  *  Retrieves a pointer to the List of Certs (certChain) that is set in the
1190  *  ValidateParams pointed to by "valParams" and stores it at "pChain". If the
1191  *  function succeeds, the pointer to the CertChain is guaranteed to be
1192  *  non-NULL.
1193  *
1194  * PARAMETERS:
1195  *  "valParams"
1196  *      Address of ValidateParams whose CertChain is to be stored.
1197  *      Must be non-NULL.
1198  *  "pChain"
1199  *      Address where object pointer will be stored. Must be non-NULL.
1200  *  "plContext"
1201  *      Platform-specific context pointer.
1202  * THREAD SAFETY:
1203  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1204  * RETURNS:
1205  *  Returns NULL if the function succeeds.
1206  *  Returns a Params Error if the function fails in a non-fatal way.
1207  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1208  */
1209 PKIX_Error *
1210 PKIX_ValidateParams_GetCertChain(
1211         PKIX_ValidateParams *valParams,
1212         PKIX_List **pChain,
1213         void *plContext);
1214 
1215 /* PKIX_TrustAnchor
1216  *
1217  * A PKIX_TrustAnchor represents a trusted entity and can be specified using a
1218  * self-signed certificate or using the trusted CA's name and public key. In
1219  * order to limit the trust in the trusted entity, name constraints can also
1220  * be imposed on the trust anchor.
1221  */
1222 
1223 /*
1224  * FUNCTION: PKIX_TrustAnchor_CreateWithCert
1225  * DESCRIPTION:
1226  *
1227  *  Creates a new TrustAnchor object using the Cert pointed to by "cert" as
1228  *  the trusted certificate and stores it at "pAnchor". Once created, a
1229  *  TrustAnchor is immutable.
1230  *
1231  * PARAMETERS:
1232  *  "cert"
1233  *      Address of Cert to use as trusted certificate. Must be non-NULL.
1234  *  "pAnchor"
1235  *      Address where object pointer will be stored. Must be non-NULL.
1236  *  "plContext"
1237  *      Platform-specific context pointer.
1238  * THREAD SAFETY:
1239  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1240  * RETURNS:
1241  *  Returns NULL if the function succeeds.
1242  *  Returns a Params Error if the function fails in a non-fatal way.
1243  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1244  */
1245 PKIX_Error *
1246 PKIX_TrustAnchor_CreateWithCert(
1247         PKIX_PL_Cert *cert,
1248         PKIX_TrustAnchor **pAnchor,
1249         void *plContext);
1250 
1251 /*
1252  * FUNCTION: PKIX_TrustAnchor_CreateWithNameKeyPair
1253  * DESCRIPTION:
1254  *
1255  *  Creates a new TrustAnchor object using the X500Name pointed to by "name",
1256  *  and the PublicKey pointed to by "pubKey" and stores it at "pAnchor". The
1257  *  CertNameConstraints pointed to by "nameConstraints" (if any) are used to
1258  *  limit the trust placed in this trust anchor. To indicate that name
1259  *  constraints don't apply, set "nameConstraints" to NULL. Once created, a
1260  *  TrustAnchor is immutable.
1261  *
1262  * PARAMETERS:
1263  *  "name"
1264  *      Address of X500Name to use as name of trusted CA. Must be non-NULL.
1265  *  "pubKey"
1266  *      Address of PublicKey to use as trusted public key. Must be non-NULL.
1267  *  "nameConstraints"
1268  *      Address of CertNameConstraints to use as initial name constraints.
1269  *      If NULL, no name constraints are applied.
1270  *  "pAnchor"
1271  *      Address where object pointer will be stored. Must be non-NULL.
1272  *  "plContext"
1273  *      Platform-specific context pointer.
1274  * THREAD SAFETY:
1275  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1276  * RETURNS:
1277  *  Returns NULL if the function succeeds.
1278  *  Returns a Params Error if the function fails in a non-fatal way.
1279  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1280  */
1281 PKIX_Error *
1282 PKIX_TrustAnchor_CreateWithNameKeyPair(
1283         PKIX_PL_X500Name *name,
1284         PKIX_PL_PublicKey *pubKey,
1285         PKIX_PL_CertNameConstraints *nameConstraints,
1286         PKIX_TrustAnchor **pAnchor,
1287         void *plContext);
1288 
1289 /*
1290  * FUNCTION: PKIX_TrustAnchor_GetTrustedCert
1291  * DESCRIPTION:
1292  *
1293  *  Retrieves a pointer to the Cert that is set in the TrustAnchor pointed to
1294  *  by "anchor" and stores it at "pCert". If "anchor" does not have a Cert
1295  *  set, this function stores NULL at "pCert".
1296  *
1297  * PARAMETERS:
1298  *  "anchor"
1299  *      Address of TrustAnchor whose Cert is to be stored. Must be non-NULL.
1300  *  "pChain"
1301  *      Address where object pointer will be stored. Must be non-NULL.
1302  *  "plContext"
1303  *      Platform-specific context pointer.
1304  * THREAD SAFETY:
1305  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1306  * RETURNS:
1307  *  Returns NULL if the function succeeds.
1308  *  Returns a Params Error if the function fails in a non-fatal way.
1309  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1310  */
1311 PKIX_Error *
1312 PKIX_TrustAnchor_GetTrustedCert(
1313         PKIX_TrustAnchor *anchor,
1314         PKIX_PL_Cert **pCert,
1315         void *plContext);
1316 
1317 /*
1318  * FUNCTION: PKIX_TrustAnchor_GetCAName
1319  * DESCRIPTION:
1320  *
1321  *  Retrieves a pointer to the CA's X500Name (if any) that is set in the
1322  *  TrustAnchor pointed to by "anchor" and stores it at "pCAName". If "anchor"
1323  *  does not have an X500Name set, this function stores NULL at "pCAName".
1324  *
1325  * PARAMETERS:
1326  *  "anchor"
1327  *      Address of TrustAnchor whose CA Name is to be stored. Must be non-NULL.
1328  *  "pCAName"
1329  *      Address where object pointer will be stored. Must be non-NULL.
1330  *  "plContext"
1331  *      Platform-specific context pointer.
1332  * THREAD SAFETY:
1333  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1334  * RETURNS:
1335  *  Returns NULL if the function succeeds.
1336  *  Returns a Params Error if the function fails in a non-fatal way.
1337  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1338  */
1339 PKIX_Error *
1340 PKIX_TrustAnchor_GetCAName(
1341         PKIX_TrustAnchor *anchor,
1342         PKIX_PL_X500Name **pCAName,
1343         void *plContext);
1344 
1345 /*
1346  * FUNCTION: PKIX_TrustAnchor_GetCAPublicKey
1347  * DESCRIPTION:
1348  *
1349  *  Retrieves a pointer to the CA's PublicKey (if any) that is set in the
1350  *  TrustAnchor pointed to by "anchor" and stores it at "pPubKey". If "anchor"
1351  *  does not have a PublicKey set, this function stores NULL at "pPubKey".
1352  *
1353  * PARAMETERS:
1354  *  "anchor"
1355  *      Address of TrustAnchor whose CA PublicKey is to be stored.
1356  *      Must be non-NULL.
1357  *  "pPubKey"
1358  *      Address where object pointer will be stored. Must be non-NULL.
1359  *  "plContext"
1360  *      Platform-specific context pointer.
1361  * THREAD SAFETY:
1362  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1363  * RETURNS:
1364  *  Returns NULL if the function succeeds.
1365  *  Returns a Params Error if the function fails in a non-fatal way.
1366  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1367  */
1368 PKIX_Error *
1369 PKIX_TrustAnchor_GetCAPublicKey(
1370         PKIX_TrustAnchor *anchor,
1371         PKIX_PL_PublicKey **pPubKey,
1372         void *plContext);
1373 
1374 /*
1375  * FUNCTION: PKIX_TrustAnchor_GetNameConstraints
1376  * DESCRIPTION:
1377  *
1378  *  Retrieves a pointer to the CertNameConstraints (if any) set in the
1379  *  TrustAnchor pointed to by "anchor" and stores it at "pConstraints". If
1380  *  "anchor" does not have any CertNameConstraints set, this function stores
1381  *  NULL at "pConstraints".
1382  *
1383  * PARAMETERS:
1384  *  "anchor"
1385  *      Address of TrustAnchor whose CertNameConstraints are to be stored.
1386  *      Must be non-NULL.
1387  *  "pConstraints"
1388  *      Address where object pointer will be stored. Must be non-NULL.
1389  *  "plContext"
1390  *      Platform-specific context pointer.
1391  * THREAD SAFETY:
1392  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1393  * RETURNS:
1394  *  Returns NULL if the function succeeds.
1395  *  Returns a Params Error if the function fails in a non-fatal way.
1396  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1397  */
1398 PKIX_Error *
1399 PKIX_TrustAnchor_GetNameConstraints(
1400         PKIX_TrustAnchor *anchor,
1401         PKIX_PL_CertNameConstraints **pNameConstraints,
1402         void *plContext);
1403 
1404 /* PKIX_ResourceLimits
1405  *
1406  *  A PKIX_ResourceLimits object represents the maximum resource usage that
1407  *  the caller desires. The ValidateChain or BuildChain call
1408  *  will not exceed these maximum limits. For example, the caller may want
1409  *  a timeout value of 1 minute, meaning that if the ValidateChain or
1410  *  BuildChain function is unable to finish in 1 minute, it should abort
1411  *  with an Error.
1412  */
1413 
1414 /*
1415  * FUNCTION: PKIX_ResourceLimits_Create
1416  * DESCRIPTION:
1417  *
1418  *  Creates a new ResourceLimits object and stores it at "pResourceLimits".
1419  *
1420  * PARAMETERS:
1421  *  "pResourceLimits"
1422  *      Address where object pointer will be stored. Must be non-NULL.
1423  *  "plContext"
1424  *      Platform-specific context pointer.
1425  * THREAD SAFETY:
1426  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1427  * RETURNS:
1428  *  Returns NULL if the function succeeds.
1429  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1430  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1431  */
1432 PKIX_Error *
1433 PKIX_ResourceLimits_Create(
1434         PKIX_ResourceLimits **pResourceLimits,
1435         void *plContext);
1436 
1437 /*
1438  * FUNCTION: PKIX_ResourceLimits_GetMaxTime
1439  * DESCRIPTION:
1440  *
1441  *  Retrieves a PKIX_UInt32 (if any) representing the maximum time that is
1442  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
1443  *  it at "pMaxTime". This maximum time (in seconds) should not be exceeded
1444  *  by the function whose ProcessingParams contain this ResourceLimits object
1445  *  (typically ValidateChain or BuildChain). It essentially functions as a
1446  *  time-out value and is only appropriate if blocking I/O is being used.
1447  *
1448  * PARAMETERS:
1449  *  "resourceLimits"
1450  *      Address of ResourceLimits object whose maximum time (in seconds) is
1451  *      to be stored. Must be non-NULL.
1452  *  "pMaxTime"
1453  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
1454  *  "plContext"
1455  *      Platform-specific context pointer.
1456  * THREAD SAFETY:
1457  *  Conditionally Thread Safe
1458  *      (see Thread Safety Definitions in Programmer's Guide)
1459  * RETURNS:
1460  *  Returns NULL if the function succeeds.
1461  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1462  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1463  */
1464 PKIX_Error *
1465 PKIX_ResourceLimits_GetMaxTime(
1466         PKIX_ResourceLimits *resourceLimits,
1467         PKIX_UInt32 *pMaxTime,
1468         void *plContext);
1469 
1470 /*
1471  * FUNCTION: PKIX_ResourceLimits_SetMaxTime
1472  * DESCRIPTION:
1473  *
1474  *  Sets the maximum time of the ResourceLimits object pointed to by
1475  *  "resourceLimits" using the PKIX_UInt32 value of "maxTime". This
1476  *  maximum time (in seconds) should not be exceeded by the function
1477  *  whose ProcessingParams contain this ResourceLimits object
1478  *  (typically ValidateChain or BuildChain). It essentially functions as a
1479  *  time-out value and is only appropriate if blocking I/O is being used.
1480  *
1481  * PARAMETERS:
1482  *  "resourceLimits"
1483  *      Address of ResourceLimits object whose maximum time (in seconds) is
1484  *      to be set. Must be non-NULL.
1485  *  "maxTime"
1486  *      Value of PKIX_UInt32 representing the maximum time (in seconds)
1487  *  "plContext"
1488  *      Platform-specific context pointer.
1489  * THREAD SAFETY:
1490  *  Not Thread Safe - assumes exclusive access to "params"
1491  *  (see Thread Safety Definitions in Programmer's Guide)
1492  * RETURNS:
1493  *  Returns NULL if the function succeeds.
1494  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1495  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1496  */
1497 PKIX_Error *
1498 PKIX_ResourceLimits_SetMaxTime(
1499         PKIX_ResourceLimits *resourceLimits,
1500         PKIX_UInt32 maxTime,
1501         void *plContext);
1502 
1503 /*
1504  * FUNCTION: PKIX_ResourceLimits_GetMaxFanout
1505  * DESCRIPTION:
1506  *
1507  *  Retrieves a PKIX_UInt32 (if any) representing the maximum fanout that is
1508  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
1509  *  it at "pMaxFanout". This maximum fanout (number of certs) should not be
1510  *  exceeded by the function whose ProcessingParams contain this ResourceLimits
1511  *  object (typically ValidateChain or BuildChain). If the builder encounters
1512  *  more than this maximum number of certificates when searching for the next
1513  *  candidate certificate, it should abort and return an error. This
1514  *  parameter is only relevant for ValidateChain if it needs to internally call
1515  *  BuildChain (e.g. in order to build the chain to a CRL's issuer).
1516  *
1517  * PARAMETERS:
1518  *  "resourceLimits"
1519  *      Address of ResourceLimits object whose maximum fanout (number of certs)
1520  *      is to be stored. Must be non-NULL.
1521  *  "pMaxFanout"
1522  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
1523  *  "plContext"
1524  *      Platform-specific context pointer.
1525  * THREAD SAFETY:
1526  *  Conditionally Thread Safe
1527  *      (see Thread Safety Definitions in Programmer's Guide)
1528  * RETURNS:
1529  *  Returns NULL if the function succeeds.
1530  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1531  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1532  */
1533 PKIX_Error *
1534 PKIX_ResourceLimits_GetMaxFanout(
1535         PKIX_ResourceLimits *resourceLimits,
1536         PKIX_UInt32 *pMaxFanout,
1537         void *plContext);
1538 
1539 /*
1540  * FUNCTION: PKIX_ResourceLimits_SetMaxFanout
1541  * DESCRIPTION:
1542  *
1543  *  Sets the maximum fanout of the ResourceLimits object pointed to by
1544  *  "resourceLimits" using the PKIX_UInt32 value of "maxFanout". This maximum
1545  *  fanout (number of certs) should not be exceeded by the function whose
1546  *  ProcessingParams contain this ResourceLimits object (typically ValidateChain
1547  *  or BuildChain). If the builder encounters more than this maximum number of
1548  *  certificates when searching for the next candidate certificate, it should
1549  *  abort and return an Error. This parameter is only relevant for ValidateChain
1550  *  if it needs to internally call BuildChain (e.g. in order to build the
1551  *  chain to a CRL's issuer).
1552  *
1553  * PARAMETERS:
1554  *  "resourceLimits"
1555  *      Address of ResourceLimits object whose maximum fanout (number of certs)
1556  *      is to be set. Must be non-NULL.
1557  *  "maxFanout"
1558  *      Value of PKIX_UInt32 representing the maximum fanout (number of certs)
1559  *  "plContext"
1560  *      Platform-specific context pointer.
1561  * THREAD SAFETY:
1562  *  Not Thread Safe - assumes exclusive access to "params"
1563  *  (see Thread Safety Definitions in Programmer's Guide)
1564  * RETURNS:
1565  *  Returns NULL if the function succeeds.
1566  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1567  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1568  */
1569 PKIX_Error *
1570 PKIX_ResourceLimits_SetMaxFanout(
1571         PKIX_ResourceLimits *resourceLimits,
1572         PKIX_UInt32 maxFanout,
1573         void *plContext);
1574 
1575 /*
1576  * FUNCTION: PKIX_ResourceLimits_GetMaxDepth
1577  * DESCRIPTION:
1578  *
1579  *  Retrieves a PKIX_UInt32 (if any) representing the maximum depth that is
1580  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
1581  *  it at "pMaxDepth". This maximum depth (number of certs) should not be
1582  *  exceeded by the function whose ProcessingParams contain this ResourceLimits
1583  *  object (typically ValidateChain or BuildChain). If the builder encounters
1584  *  more than this maximum number of certificates when searching for the next
1585  *  candidate certificate, it should abort and return an error. This
1586  *  parameter is only relevant for ValidateChain if it needs to internally call
1587  *  BuildChain (e.g. in order to build the chain to a CRL's issuer).
1588  *
1589  * PARAMETERS:
1590  *  "resourceLimits"
1591  *      Address of ResourceLimits object whose maximum depth (number of certs)
1592  *      is to be stored. Must be non-NULL.
1593  *  "pMaxDepth"
1594  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
1595  *  "plContext"
1596  *      Platform-specific context pointer.
1597  * THREAD SAFETY:
1598  *  Conditionally Thread Safe
1599  *      (see Thread Safety Definitions in Programmer's Guide)
1600  * RETURNS:
1601  *  Returns NULL if the function succeeds.
1602  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1603  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1604  */
1605 PKIX_Error *
1606 PKIX_ResourceLimits_GetMaxDepth(
1607         PKIX_ResourceLimits *resourceLimits,
1608         PKIX_UInt32 *pMaxDepth,
1609         void *plContext);
1610 
1611 /*
1612  * FUNCTION: PKIX_ResourceLimits_SetMaxDepth
1613  * DESCRIPTION:
1614  *
1615  *  Sets the maximum depth of the ResourceLimits object pointed to by
1616  *  "resourceLimits" using the PKIX_UInt32 value of "maxDepth". This maximum
1617  *  depth (number of certs) should not be exceeded by the function whose
1618  *  ProcessingParams contain this ResourceLimits object (typically ValidateChain
1619  *  or BuildChain). If the builder encounters more than this maximum number of
1620  *  certificates when searching for the next candidate certificate, it should
1621  *  abort and return an Error. This parameter is only relevant for ValidateChain
1622  *  if it needs to internally call BuildChain (e.g. in order to build the
1623  *  chain to a CRL's issuer).
1624  *
1625  * PARAMETERS:
1626  *  "resourceLimits"
1627  *      Address of ResourceLimits object whose maximum depth (number of certs)
1628  *      is to be set. Must be non-NULL.
1629  *  "maxDepth"
1630  *      Value of PKIX_UInt32 representing the maximum depth (number of certs)
1631  *  "plContext"
1632  *      Platform-specific context pointer.
1633  * THREAD SAFETY:
1634  *  Not Thread Safe - assumes exclusive access to "params"
1635  *  (see Thread Safety Definitions in Programmer's Guide)
1636  * RETURNS:
1637  *  Returns NULL if the function succeeds.
1638  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1639  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1640  */
1641 PKIX_Error *
1642 PKIX_ResourceLimits_SetMaxDepth(
1643         PKIX_ResourceLimits *resourceLimits,
1644         PKIX_UInt32 maxDepth,
1645         void *plContext);
1646 
1647 /*
1648  * FUNCTION: PKIX_ResourceLimits_GetMaxNumberOfCerts
1649  * DESCRIPTION:
1650  *
1651  *  Retrieves a PKIX_UInt32 (if any) representing the maximum number of traversed
1652  *  certs that is set in the ResourceLimits object pointed to by "resourceLimits"
1653  *  and stores it at "pMaxNumber". This maximum number of traversed certs should
1654  *  not be exceeded by the function whose ProcessingParams contain this ResourceLimits
1655  *  object (typically ValidateChain or BuildChain). If the builder traverses more
1656  *  than this number of certs during the build process, it should abort and
1657  *  return an Error. This parameter is only relevant for ValidateChain if it
1658  *  needs to internally call BuildChain (e.g. in order to build the chain to a
1659  *  CRL's issuer).
1660  *
1661  * PARAMETERS:
1662  *  "resourceLimits"
1663  *      Address of ResourceLimits object whose maximum number of traversed certs
1664  *      is to be stored. Must be non-NULL.
1665  *  "pMaxNumber"
1666  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
1667  *  "plContext"
1668  *      Platform-specific context pointer.
1669  * THREAD SAFETY:
1670  *  Conditionally Thread Safe
1671  *      (see Thread Safety Definitions in Programmer's Guide)
1672  * RETURNS:
1673  *  Returns NULL if the function succeeds.
1674  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1675  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1676  */
1677 PKIX_Error *
1678 PKIX_ResourceLimits_GetMaxNumberOfCerts(
1679         PKIX_ResourceLimits *resourceLimits,
1680         PKIX_UInt32 *pMaxNumber,
1681         void *plContext);
1682 
1683 /*
1684  * FUNCTION: PKIX_ResourceLimits_SetMaxNumberOfCerts
1685  * DESCRIPTION:
1686  *
1687  *  Sets the maximum number of traversed certs of the ResourceLimits object
1688  *  pointed to by "resourceLimits" using the PKIX_UInt32 value of "maxNumber".
1689  *  This maximum number of traversed certs should not be exceeded by the function
1690  *  whose ProcessingParams contain this ResourceLimits object (typically ValidateChain
1691  *  or BuildChain). If the builder traverses more than this number of certs
1692  *  during the build process, it should abort and return an Error. This parameter
1693  *  is only relevant for ValidateChain if it needs to internally call BuildChain
1694  *  (e.g. in order to build the chain to a CRL's issuer).
1695  *
1696  * PARAMETERS:
1697  *  "resourceLimits"
1698  *      Address of ResourceLimits object whose maximum number of traversed certs
1699  *      is to be set. Must be non-NULL.
1700  *  "maxNumber"
1701  *      Value of PKIX_UInt32 representing the maximum number of traversed certs
1702  *  "plContext"
1703  *      Platform-specific context pointer.
1704  * THREAD SAFETY:
1705  *  Not Thread Safe - assumes exclusive access to "params"
1706  *  (see Thread Safety Definitions in Programmer's Guide)
1707  * RETURNS:
1708  *  Returns NULL if the function succeeds.
1709  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1710  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1711  */
1712 PKIX_Error *
1713 PKIX_ResourceLimits_SetMaxNumberOfCerts(
1714         PKIX_ResourceLimits *resourceLimits,
1715         PKIX_UInt32 maxNumber,
1716         void *plContext);
1717 
1718 /*
1719  * FUNCTION: PKIX_ResourceLimits_GetMaxNumberOfCRLs
1720  * DESCRIPTION:
1721  *
1722  *  Retrieves a PKIX_UInt32 (if any) representing the maximum number of traversed
1723  *  CRLs that is set in the ResourceLimits object pointed to by "resourceLimits"
1724  *  and stores it at "pMaxNumber". This maximum number of traversed CRLs should
1725  *  not be exceeded by the function whose ProcessingParams contain this ResourceLimits
1726  *  object (typically ValidateChain or BuildChain). If the builder traverses more
1727  *  than this number of CRLs during the build process, it should abort and
1728  *  return an Error. This parameter is only relevant for ValidateChain if it
1729  *  needs to internally call BuildChain (e.g. in order to build the chain to a
1730  *  CRL's issuer).
1731  *
1732  * PARAMETERS:
1733  *  "resourceLimits"
1734  *      Address of ResourceLimits object whose maximum number of traversed CRLs
1735  *      is to be stored. Must be non-NULL.
1736  *  "pMaxNumber"
1737  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
1738  *  "plContext"
1739  *      Platform-specific context pointer.
1740  * THREAD SAFETY:
1741  *  Conditionally Thread Safe
1742  *      (see Thread Safety Definitions in Programmer's Guide)
1743  * RETURNS:
1744  *  Returns NULL if the function succeeds.
1745  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1746  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1747  */
1748 PKIX_Error *
1749 PKIX_ResourceLimits_GetMaxNumberOfCRLs(
1750         PKIX_ResourceLimits *resourceLimits,
1751         PKIX_UInt32 *pMaxNumber,
1752         void *plContext);
1753 
1754 /*
1755  * FUNCTION: PKIX_ResourceLimits_SetMaxNumberOfCRLs
1756  * DESCRIPTION:
1757  *
1758  *  Sets the maximum number of traversed CRLs of the ResourceLimits object
1759  *  pointed to by "resourceLimits" using the PKIX_UInt32 value of "maxNumber".
1760  *  This maximum number of traversed CRLs should not be exceeded by the function
1761  *  whose ProcessingParams contain this ResourceLimits object (typically ValidateChain
1762  *  or BuildChain). If the builder traverses more than this number of CRLs
1763  *  during the build process, it should abort and return an Error. This parameter
1764  *  is only relevant for ValidateChain if it needs to internally call BuildChain
1765  *  (e.g. in order to build the chain to a CRL's issuer).
1766  *
1767  * PARAMETERS:
1768  *  "resourceLimits"
1769  *      Address of ResourceLimits object whose maximum number of traversed CRLs
1770  *      is to be set. Must be non-NULL.
1771  *  "maxNumber"
1772  *      Value of PKIX_UInt32 representing the maximum number of traversed CRLs
1773  *  "plContext"
1774  *      Platform-specific context pointer.
1775  * THREAD SAFETY:
1776  *  Not Thread Safe - assumes exclusive access to "params"
1777  *  (see Thread Safety Definitions in Programmer's Guide)
1778  * RETURNS:
1779  *  Returns NULL if the function succeeds.
1780  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
1781  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1782  */
1783 PKIX_Error *
1784 PKIX_ResourceLimits_SetMaxNumberOfCRLs(
1785         PKIX_ResourceLimits *resourceLimits,
1786         PKIX_UInt32 maxNumber,
1787         void *plContext);
1788 
1789 #ifdef __cplusplus
1790 }
1791 #endif
1792 
1793 #endif /* _PKIX_PARAMS_H */
1794