1 /* This Source Code Form is subject to the terms of the Mozilla Public
2  * License, v. 2.0. If a copy of the MPL was not distributed with this
3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4 /*
5  * This file defines functions associated with the PKIX_CRLSelector and the
6  * PKIX_ComCRLSelParams types.
7  *
8  */
9 
10 
11 #ifndef _PKIX_CRLSEL_H
12 #define _PKIX_CRLSEL_H
13 
14 #include "pkixt.h"
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 /* General
21  *
22  * Please refer to the libpkix Programmer's Guide for detailed information
23  * about how to use the libpkix library. Certain key warnings and notices from
24  * that document are repeated here for emphasis.
25  *
26  * All identifiers in this file (and all public identifiers defined in
27  * libpkix) begin with "PKIX_". Private identifiers only intended for use
28  * within the library begin with "pkix_".
29  *
30  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
31  *
32  * Unless otherwise noted, for all accessor (gettor) functions that return a
33  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
34  * shared object. Therefore, the caller should treat this shared object as
35  * read-only and should not modify this shared object. When done using the
36  * shared object, the caller should release the reference to the object by
37  * using the PKIX_PL_Object_DecRef function.
38  *
39  * While a function is executing, if its arguments (or anything referred to by
40  * its arguments) are modified, free'd, or destroyed, the function's behavior
41  * is undefined.
42  *
43  */
44 
45 /* PKIX_CRLSelector
46  *
47  * PKIX_CRLSelectors provide a standard way for the caller to select CRLs
48  * based on particular criteria. A CRLSelector is typically used by libpkix
49  * to retrieve CRLs from a CertStore during certificate chain validation or
50  * building. (see pkix_certstore.h) For example, the caller may wish to only
51  * select those CRLs that have a particular issuer or a particular value for a
52  * private CRL extension. The MatchCallback allows the caller to specify the
53  * custom matching logic to be used by a CRLSelector.
54 
55  * By default, the MatchCallback is set to point to the default implementation
56  * provided by libpkix, which understands how to process the most common
57  * parameters. If the default implementation is used, the caller should set
58  * these common parameters using PKIX_CRLSelector_SetCommonCRLSelectorParams.
59  * Any common parameter that is not set is assumed to be disabled, which means
60  * the default MatchCallback implementation will select all CRLs without
61  * regard to that particular disabled parameter. For example, if the
62  * MaxCRLNumber parameter is not set, MatchCallback will not filter out any
63  * CRL based on its CRL number. As such, if no parameters are set, all are
64  * disabled and any CRL will match. If a parameter is disabled, its associated
65  * PKIX_ComCRLSelParams_Get* function returns a default value of NULL.
66  *
67  * If a custom implementation is desired, the default implementation can be
68  * overridden by calling PKIX_CRLSelector_SetMatchCallback. In this case, the
69  * CRLSelector can be initialized with a crlSelectorContext, which is where
70  * the caller can specify the desired parameters the caller wishes to match
71  * against. Note that this crlSelectorContext must be a PKIX_PL_Object,
72  * allowing it to be reference-counted and allowing it to provide the standard
73  * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
74  *
75  */
76 
77 /*
78  * FUNCTION: PKIX_CRLSelector_MatchCallback
79  * DESCRIPTION:
80  *
81  *  This callback function determines whether the specified CRL pointed to by
82  *  "crl" matches the criteria of the CRLSelector pointed to by "selector".
83  *  If the CRL matches the CRLSelector's criteria, PKIX_TRUE is stored at
84  *  "pMatch". Otherwise PKIX_FALSE is stored at "pMatch".
85  *
86  * PARAMETERS:
87  *  "selector"
88  *      Address of CRLSelector whose MatchCallback logic and parameters are
89  *      to be used. Must be non-NULL.
90  *  "crl"
91  *      Address of CRL that is to be matched using "selector". Must be non-NULL.
92  *  "pMatch"
93  *      Address at which Boolean result is stored. Must be non-NULL.
94  *  "plContext"
95  *      Platform-specific context pointer.
96  * THREAD SAFETY:
97  *  Thread Safe
98  *
99  *  Multiple threads must be able to safely call this function without
100  *  worrying about conflicts, even if they're operating on the same objects.
101  * RETURNS:
102  *  Returns NULL if the function succeeds.
103  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
104  *  Returns a Fatal Error if the function fails in an unrecoverable way.
105  */
106 typedef PKIX_Error *
107 (*PKIX_CRLSelector_MatchCallback)(
108         PKIX_CRLSelector *selector,
109         PKIX_PL_CRL *crl,
110         PKIX_Boolean *pMatch,
111         void *plContext);
112 
113 /*
114  * FUNCTION: PKIX_CRLSelector_Create
115  * DESCRIPTION:
116  *
117  *  Creates a new CRLSelector using the Object pointed to by
118  *  "crlSelectorContext" (if any) and stores it at "pSelector". As noted
119  *  above, by default, the MatchCallback is set to point to the default
120  *  implementation provided by libpkix, which understands how to process
121  *  ComCRLSelParams. This is overridden if the MatchCallback pointed to by
122  *  "callback" is not NULL, in which case the parameters are specified using
123  *  the Object pointed to by "crlSelectorContext".
124  *
125  * PARAMETERS:
126  *  "issue"
127  *      crl issuer.
128  *  "crlDpList"
129  *      distribution points list
130  *  "callback"
131  *      The MatchCallback function to be used.
132  *  "pSelector"
133  *      Address where object pointer will be stored. Must be non-NULL.
134  *  "plContext"
135  *      Platform-specific context pointer.
136  * THREAD SAFETY:
137  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
138  * RETURNS:
139  *  Returns NULL if the function succeeds.
140  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
141  *  Returns a Fatal Error if the function fails in an unrecoverable way.
142  */
143 PKIX_Error *
144 PKIX_CRLSelector_Create(
145         PKIX_PL_Cert *issuer,
146         PKIX_List *crlDpList,
147         PKIX_PL_Date *date,
148         PKIX_CRLSelector **pSelector,
149         void *plContext);
150 
151 /*
152  * FUNCTION: PKIX_CRLSelector_GetMatchCallback
153  * DESCRIPTION:
154  *
155  *  Retrieves a pointer to "selector's" Match callback function and puts it in
156  *  "pCallback".
157  *
158  * PARAMETERS:
159  *  "selector"
160  *      The CRLSelector whose Match callback is desired. Must be non-NULL.
161  *  "pCallback"
162  *      Address where Match callback function pointer will be stored.
163  *      Must be non-NULL.
164  *  "plContext"
165  *      Platform-specific context pointer.
166  * THREAD SAFETY:
167  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
168  * RETURNS:
169  *  Returns NULL if the function succeeds.
170  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
171  *  Returns a Fatal Error if the function fails in an unrecoverable way.
172  */
173 PKIX_Error *
174 PKIX_CRLSelector_GetMatchCallback(
175         PKIX_CRLSelector *selector,
176         PKIX_CRLSelector_MatchCallback *pCallback,
177         void *plContext);
178 
179 /*
180  * FUNCTION: PKIX_CRLSelector_GetCRLSelectorContext
181  * DESCRIPTION:
182  *
183  *  Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
184  *  of the CRLSelector pointed to by "selector" and stores it at
185  *  "pCRLSelectorContext".
186  *
187  * PARAMETERS:
188  *  "selector"
189  *      Address of CRLSelector whose context is to be stored. Must be non-NULL.
190  *  "pCRLSelectorContext"
191  *      Address where object pointer will be stored. Must be non-NULL.
192  *  "plContext"
193  *      Platform-specific context pointer.
194  * THREAD SAFETY:
195  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
196  * RETURNS:
197  *  Returns NULL if the function succeeds.
198  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
199  *  Returns a Fatal Error if the function fails in an unrecoverable way.
200  */
201 PKIX_Error *
202 PKIX_CRLSelector_GetCRLSelectorContext(
203         PKIX_CRLSelector *selector,
204         void **pCRLSelectorContext,
205         void *plContext);
206 
207 /*
208  * FUNCTION: PKIX_CRLSelector_GetCommonCRLSelectorParams
209  * DESCRIPTION:
210  *
211  *  Retrieves a pointer to the ComCRLSelParams object that represent the common
212  *  parameters of the CRLSelector pointed to by "selector" and stores it at
213  *  "pCommonCRLSelectorParams". If there are no common parameters stored with
214  *  the CRLSelector, this function stores NULL at "pCommonCRLSelectorParams".
215  *
216  * PARAMETERS:
217  *  "selector"
218  *      Address of CRLSelector whose ComCRLSelParams are to be stored.
219  *      Must be non-NULL.
220  *  "pCommonCRLSelectorParams"
221  *      Address where object pointer will be stored. Must be non-NULL.
222  *  "plContext"
223  *      Platform-specific context pointer.
224  * THREAD SAFETY:
225  *  Conditionally Thread Safe
226  *      (see Thread Safety Definitions in Programmer's Guide)
227  * RETURNS:
228  *  Returns NULL if the function succeeds.
229  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
230  *  Returns a Fatal Error if the function fails in an unrecoverable way.
231  */
232 PKIX_Error *
233 PKIX_CRLSelector_GetCommonCRLSelectorParams(
234         PKIX_CRLSelector *selector,
235         PKIX_ComCRLSelParams **pCommonCRLSelectorParams,
236         void *plContext);
237 
238 /*
239  * FUNCTION: PKIX_CRLSelector_SetCommonCRLSelectorParams
240  * DESCRIPTION:
241  *
242  *  Sets the common parameters for the CRLSelector pointed to by "selector"
243  *  using the ComCRLSelParams pointed to by "commonCRLSelectorParams".
244  *
245  * PARAMETERS:
246  *  "selector"
247  *      Address of CRLSelector whose common parameters are to be set.
248  *      Must be non-NULL.
249  *  "commonCRLSelectorParams"
250  *      Address of ComCRLSelParams representing the common parameters.
251  *  "plContext"
252  *      Platform-specific context pointer.
253  * THREAD SAFETY:
254  *  Not Thread Safe - assumes exclusive access to "selector"
255  *  (see Thread Safety Definitions in Programmer's Guide)
256  * RETURNS:
257  *  Returns NULL if the function succeeds.
258  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
259  *  Returns a Fatal Error if the function fails in an unrecoverable way.
260  */
261 PKIX_Error *
262 PKIX_CRLSelector_SetCommonCRLSelectorParams(
263         PKIX_CRLSelector *selector,
264         PKIX_ComCRLSelParams *commonCRLSelectorParams,
265         void *plContext);
266 
267 /* PKIX_ComCRLSelParams
268  *
269  * PKIX_ComCRLSelParams are X.509 parameters commonly used with CRLSelectors,
270  * especially determining which CRLs to retrieve from a CertStore.
271  * PKIX_ComCRLSelParams are typically used with those CRLSelectors that use
272  * the default implementation of MatchCallback, which understands how to
273  * process ComCRLSelParams.
274  */
275 
276 /*
277  * FUNCTION: PKIX_ComCRLSelParams_Create
278  * DESCRIPTION:
279  *
280  *  Creates a new ComCRLSelParams object and stores it at "pParams".
281  *
282  * PARAMETERS:
283  *  "pParams"
284  *      Address where object pointer will be stored. Must be non-NULL.
285  *  "plContext"
286  *      Platform-specific context pointer.
287  * THREAD SAFETY:
288  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
289  * RETURNS:
290  *  Returns NULL if the function succeeds.
291  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
292  *  Returns a Fatal Error if the function fails in an unrecoverable way.
293  */
294 PKIX_Error *
295 PKIX_ComCRLSelParams_Create(
296         PKIX_ComCRLSelParams **pParams,
297         void *plContext);
298 
299 /*
300  * FUNCTION: PKIX_ComCRLSelParams_GetIssuerNames
301  * DESCRIPTION:
302  *
303  *  Retrieves a pointer to the List of X500Names (if any) representing the
304  *  issuer names criterion that is set in the ComCRLSelParams pointed to by
305  *  "params" and stores it at "pNames". In order to match against this
306  *  criterion, a CRL's IssuerName must match at least one of the criterion's
307  *  issuer names.
308  *
309  *  If "params" does not have this criterion set, this function stores NULL at
310  *  "pNames", in which case all CRLs are considered to match.
311  *
312  *  Note that the List returned by this function is immutable.
313  *
314  * PARAMETERS:
315  *  "params"
316  *      Address of ComCRLSelParams whose issuer names criterion (if any) is to
317  *      be stored. Must be non-NULL.
318  *  "pNames"
319  *      Address where object pointer will be stored. Must be non-NULL.
320  *  "plContext"
321  *      Platform-specific context pointer.
322  * THREAD SAFETY:
323  *  Conditionally Thread Safe
324  *      (see Thread Safety Definitions in Programmer's Guide)
325  * RETURNS:
326  *  Returns NULL if the function succeeds.
327  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
328  *  Returns a Fatal Error if the function fails in an unrecoverable way.
329  */
330 PKIX_Error *
331 PKIX_ComCRLSelParams_GetIssuerNames(
332         PKIX_ComCRLSelParams *params,
333         PKIX_List **pNames,  /* list of PKIX_PL_X500Name */
334         void *plContext);
335 
336 /*
337  * FUNCTION: PKIX_ComCRLSelParams_SetIssuerNames
338  * DESCRIPTION:
339  *
340  *  Sets the issuer names criterion of the ComCRLSelParams pointed to by
341  *  "params" using a List of X500Names pointed to by "names". In order to match
342  *  against this criterion, a CRL's IssuerName must match at least one of the
343  *  criterion's issuer names.
344  *
345  * PARAMETERS:
346  *  "params"
347  *      Address of ComCRLSelParamsParams whose issuer names criterion is to be
348  *      set. Must be non-NULL.
349  *  "names"
350  *      Address of List of X500Names used to set the criterion
351  *  "plContext"
352  *      Platform-specific context pointer.
353  * THREAD SAFETY:
354  *  Not Thread Safe - assumes exclusive access to "params"
355  *  (see Thread Safety Definitions in Programmer's Guide)
356  * RETURNS:
357  *  Returns NULL if the function succeeds.
358  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
359  *  Returns a Fatal Error if the function fails in an unrecoverable way.
360  */
361 PKIX_Error *
362 PKIX_ComCRLSelParams_SetIssuerNames(
363         PKIX_ComCRLSelParams *params,
364         PKIX_List *names,   /* list of PKIX_PL_X500Name */
365         void *plContext);
366 
367 /*
368  * FUNCTION: PKIX_ComCRLSelParams_AddIssuerName
369  * DESCRIPTION:
370  *
371  *  Adds to the issuer names criterion of the ComCRLSelParams pointed to by
372  *  "params" using the X500Name pointed to by "name". In order to match
373  *  against this criterion, a CRL's IssuerName must match at least one of the
374  *  criterion's issuer names.
375  *
376  * PARAMETERS:
377  *  "params"
378  *      Address of ComCRLSelParams whose issuer names criterion is to be added
379  *      to. Must be non-NULL.
380  *  "name"
381  *      Address of X500Name to be added.
382  *  "plContext"
383  *      Platform-specific context pointer.
384  * THREAD SAFETY:
385  *  Not Thread Safe - assumes exclusive access to "params"
386  *  (see Thread Safety Definitions in Programmer's Guide)
387  * RETURNS:
388  *  Returns NULL if the function succeeds.
389  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
390  *  Returns a Fatal Error if the function fails in an unrecoverable way.
391  */
392 PKIX_Error *
393 PKIX_ComCRLSelParams_AddIssuerName(
394         PKIX_ComCRLSelParams *params,
395         PKIX_PL_X500Name *name,
396         void *plContext);
397 
398 /*
399  * FUNCTION: PKIX_ComCRLSelParams_GetCertificateChecking
400  * DESCRIPTION:
401  *
402  *  Retrieves a pointer to the Cert (if any) representing the certificate whose
403  *  revocation status is being checked. This is not a criterion. It is simply
404  *  optional information that may help a CertStore find relevant CRLs.
405  *
406  *  If "params" does not have a certificate set, this function stores NULL at
407  *  "pCert", in which case there is no optional information to provide.
408  *
409  * PARAMETERS:
410  *  "params"
411  *      Address of ComCRLSelParams whose certificate being checked (if any) is
412  *      to be stored. Must be non-NULL.
413  *  "pCert"
414  *      Address where object pointer will be stored. Must be non-NULL.
415  *  "plContext"
416  *      Platform-specific context pointer.
417  * THREAD SAFETY:
418  *  Conditionally Thread Safe
419  *      (see Thread Safety Definitions in Programmer's Guide)
420  * RETURNS:
421  *  Returns NULL if the function succeeds
422  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
423  *  Returns a Fatal Error if the function fails in an unrecoverable way.
424  */
425 PKIX_Error *
426 PKIX_ComCRLSelParams_GetCertificateChecking(
427         PKIX_ComCRLSelParams *params,
428         PKIX_PL_Cert **pCert,
429         void *plContext);
430 
431 /*
432  * FUNCTION: PKIX_ComCRLSelParams_SetCertificateChecking
433  * DESCRIPTION:
434  *
435  *  Sets the ComCRLSelParams pointed to by "params" with the certificate
436  *  (pointed to by "cert") whose revocation status is being checked. This is
437  *  not a criterion. It is simply optional information that may help a
438  *  CertStore find relevant CRLs.
439  *
440  * PARAMETERS:
441  *  "params"
442  *      Address of ComCRLSelParams whose certificate being checked is to be
443  *      set. Must be non-NULL.
444  *  "cert"
445  *      Address of Cert whose revocation status is being checked
446  *  "plContext"
447  *      Platform-specific context pointer.
448  * THREAD SAFETY:
449  *  Not Thread Safe - assumes exclusive access to "params"
450  *  (see Thread Safety Definitions in Programmer's Guide)
451  * RETURNS:
452  *  Returns NULL if the function succeeds.
453  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
454  *  Returns a Fatal Error if the function fails in an unrecoverable way.
455  */
456 PKIX_Error *
457 PKIX_ComCRLSelParams_SetCertificateChecking(
458         PKIX_ComCRLSelParams *params,
459         PKIX_PL_Cert *cert,
460         void *plContext);
461 
462 /*
463  * FUNCTION: PKIX_ComCRLSelParams_GetDateAndTime
464  * DESCRIPTION:
465  *
466  *  Retrieves a pointer to the Date (if any) representing the dateAndTime
467  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
468  *  stores it at "pDate". In order to match against this criterion, a CRL's
469  *  thisUpdate component must be less than or equal to the criterion's
470  *  dateAndTime and the CRL's nextUpdate component must be later than the
471  *  criterion's dateAndTime. There is no match if the CRL does not contain a
472  *  nextUpdate component.
473  *
474  *  If "params" does not have this criterion set, this function stores NULL at
475  *  "pDate", in which case all CRLs are considered to match.
476  *
477  * PARAMETERS:
478  *  "params"
479  *      Address of ComCRLSelParams whose dateAndTime criterion (if any) is to
480  *      be stored. Must be non-NULL.
481  *  "pDate"
482  *      Address where object pointer will be stored. Must be non-NULL.
483  *  "plContext"
484  *      Platform-specific context pointer.
485  * THREAD SAFETY:
486  *  Conditionally Thread Safe
487  *      (see Thread Safety Definitions in Programmer's Guide)
488  * RETURNS:
489  *  Returns NULL if the function succeeds.
490  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
491  *  Returns a Fatal Error if the function fails in an unrecoverable way.
492  */
493 PKIX_Error *
494 PKIX_ComCRLSelParams_GetDateAndTime(
495         PKIX_ComCRLSelParams *params,
496         PKIX_PL_Date **pDate,
497         void *plContext);
498 
499 /*
500  * FUNCTION: PKIX_ComCRLSelParams_SetDateAndTime
501  * DESCRIPTION:
502  *
503  *  Sets the dateAndTime criterion of the ComCRLSelParams pointed to by
504  *  "params" using a Date pointed to by "date". In order to match against this
505  *  criterion, a CRL's thisUpdate component must be less than or equal to the
506  *  criterion's dateAndTime and the CRL's nextUpdate component must be later
507  *  than the criterion's dateAndTime. There is no match if the CRL does not
508  *  contain a nextUpdate component.
509  *
510  * PARAMETERS:
511  *  "params"
512  *      Address of ComCRLSelParamsParams whose dateAndTime criterion is to be
513  *      set. Must be non-NULL.
514  *  "date"
515  *      Address of Date used to set the criterion
516  *  "plContext"
517  *      Platform-specific context pointer.
518  * THREAD SAFETY:
519  *  Not Thread Safe - assumes exclusive access to "params"
520  *  (see Thread Safety Definitions in Programmer's Guide)
521  * RETURNS:
522  *  Returns NULL if the function succeeds.
523  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
524  *  Returns a Fatal Error if the function fails in an unrecoverable way.
525  */
526 PKIX_Error *
527 PKIX_ComCRLSelParams_SetDateAndTime(
528         PKIX_ComCRLSelParams *params,
529         PKIX_PL_Date *date,
530         void *plContext);
531 
532 /*
533  * FUNCTION: PKIX_ComCRLSelParams_GetNISTPolicyEnabled
534  * DESCRIPTION:
535  *
536  *  Retrieves a pointer to the Boolean representing the NIST CRL policy
537  *  activation flag that is set in the ComCRLSelParams pointed to by "params"
538  *  and stores it at "enabled". If enabled, a CRL must have nextUpdate field.
539  *
540  *  Default value for this flag is TRUE.
541  *
542  * PARAMETERS:
543  *  "params"
544  *      Address of ComCRLSelParams whose NIST CRL policy criterion  is to
545  *      be stored. Must be non-NULL.
546  *  "pEnabled"
547  *      Address where object pointer will be stored. Must be non-NULL.
548  *  "plContext"
549  *      Platform-specific context pointer.
550  * THREAD SAFETY:
551  *  Conditionally Thread Safe
552  *      (see Thread Safety Definitions in Programmer's Guide)
553  * RETURNS:
554  *  Returns NULL if the function succeeds.
555  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
556  *  Returns a Fatal Error if the function fails in an unrecoverable way.
557  */
558 PKIX_Error *
559 PKIX_ComCRLSelParams_GetNISTPolicyEnabled(
560         PKIX_ComCRLSelParams *params,
561         PKIX_Boolean *pEnabled,
562         void *plContext);
563 
564 /*
565  * FUNCTION: PKIX_ComCRLSelParams_SetNISTPolicyEnabled
566  * DESCRIPTION:
567  *
568  *  Sets the NIST crl policy criterion of the ComCRLSelParams pointed to by
569  *  "params" using a "enabled" flag. In order to match against this
570  *  criterion, a CRL's nextUpdate must be available and criterion's
571  *  dataAndTime must be within thisUpdate and nextUpdate time period.
572  *
573  * PARAMETERS:
574  *  "params"
575  *      Address of ComCRLSelParamsParams whose NIST CRL policy criterion
576  *      is to be set. Must be non-NULL.
577  *  "enabled"
578  *      Address of Bollean used to set the criterion
579  *  "plContext"
580  *      Platform-specific context pointer.
581  * THREAD SAFETY:
582  *  Not Thread Safe - assumes exclusive access to "params"
583  *  (see Thread Safety Definitions in Programmer's Guide)
584  * RETURNS:
585  *  Returns NULL if the function succeeds.
586  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
587  *  Returns a Fatal Error if the function fails in an unrecoverable way.
588  */
589 PKIX_Error *
590 PKIX_ComCRLSelParams_SetNISTPolicyEnabled(
591         PKIX_ComCRLSelParams *params,
592         PKIX_Boolean enabled,
593         void *plContext);
594 
595 /*
596  * FUNCTION: PKIX_ComCRLSelParams_GetMaxCRLNumber
597  * DESCRIPTION:
598  *
599  *  Retrieves a pointer to the BigInt (if any) representing the maxCRLNumber
600  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
601  *  stores it at "pNumber". In order to match against this criterion, a CRL
602  *  must have a CRL number extension whose value is less than or equal to the
603  *  criterion's value.
604  *
605  *  If "params" does not have this criterion set, this function stores NULL at
606  *  "pNumber", in which case all CRLs are considered to match.
607  *
608  * PARAMETERS:
609  *  "params"
610  *      Address of ComCRLSelParams whose maxCRLNumber criterion (if any) is to
611  *      be stored. Must be non-NULL.
612  *  "pNumber"
613  *      Address where object pointer will be stored. Must be non-NULL.
614  *  "plContext"
615  *      Platform-specific context pointer.
616  * THREAD SAFETY:
617  *  Conditionally Thread Safe
618  *      (see Thread Safety Definitions in Programmer's Guide)
619  * RETURNS:
620  *  Returns NULL if the function succeeds.
621  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
622  *  Returns a Fatal Error if the function fails in an unrecoverable way.
623  */
624 PKIX_Error *
625 PKIX_ComCRLSelParams_GetMaxCRLNumber(
626         PKIX_ComCRLSelParams *params,
627         PKIX_PL_BigInt **pNumber,
628         void *plContext);
629 
630 /*
631  * FUNCTION: PKIX_ComCRLSelParams_SetMaxCRLNumber
632  * DESCRIPTION:
633  *
634  *  Sets the maxCRLNumber criterion of the ComCRLSelParams pointed to by
635  *  "params" using a BigInt pointed to by "number". In order to match against
636  *  this criterion, a CRL must have a CRL number extension whose value is less
637  *  than or equal to the criterion's value.
638  *
639  * PARAMETERS:
640  *  "params"
641  *      Address of ComCRLSelParamsParams whose maxCRLNumber criterion is to be
642  *      set. Must be non-NULL.
643  *  "number"
644  *      Address of BigInt used to set the criterion
645  *  "plContext"
646  *      Platform-specific context pointer.
647  * THREAD SAFETY:
648  *  Not Thread Safe - assumes exclusive access to "params"
649  *  (see Thread Safety Definitions in Programmer's Guide)
650  * RETURNS:
651  *  Returns NULL if the function succeeds.
652  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
653  *  Returns a Fatal Error if the function fails in an unrecoverable way.
654  */
655 PKIX_Error *
656 PKIX_ComCRLSelParams_SetMaxCRLNumber(
657         PKIX_ComCRLSelParams *params,
658         PKIX_PL_BigInt *number,
659         void *plContext);
660 
661 /*
662  * FUNCTION: PKIX_ComCRLSelParams_GetMinCRLNumber
663  * DESCRIPTION:
664  *
665  *  Retrieves a pointer to the BigInt (if any) representing the minCRLNumber
666  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
667  *  stores it at "pNumber". In order to match against this criterion, a CRL
668  *  must have a CRL number extension whose value is greater than or equal to
669  *  the criterion's value.
670  *
671  *  If "params" does not have this criterion set, this function stores NULL at
672  *  "pNumber", in which case all CRLs are considered to match.
673  *
674  * PARAMETERS:
675  *  "params"
676  *      Address of ComCRLSelParams whose minCRLNumber criterion (if any) is to
677  *      be stored. Must be non-NULL.
678  *  "pNumber"
679  *      Address where object pointer will be stored. Must be non-NULL.
680  *  "plContext"
681  *      Platform-specific context pointer.
682  * THREAD SAFETY:
683  *  Conditionally Thread Safe
684  *      (see Thread Safety Definitions in Programmer's Guide)
685  * RETURNS:
686  *  Returns NULL if the function succeeds.
687  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
688  *  Returns a Fatal Error if the function fails in an unrecoverable way.
689  */
690 PKIX_Error *
691 PKIX_ComCRLSelParams_GetMinCRLNumber(
692         PKIX_ComCRLSelParams *params,
693         PKIX_PL_BigInt **pNumber,
694         void *plContext);
695 
696 /*
697  * FUNCTION: PKIX_ComCRLSelParams_SetMinCRLNumber
698  * DESCRIPTION:
699  *
700  *  Sets the minCRLNumber criterion of the ComCRLSelParams pointed to by
701  *  "params" using a BigInt pointed to by "number". In order to match against
702  *  this criterion, a CRL must have a CRL number extension whose value is
703  *  greater than or equal to the criterion's value.
704  *
705  * PARAMETERS:
706  *  "params"
707  *      Address of ComCRLSelParamsParams whose minCRLNumber criterion is to be
708  *      set. Must be non-NULL.
709  *  "number"
710  *      Address of BigInt used to set the criterion
711  *  "plContext"
712  *      Platform-specific context pointer.
713  * THREAD SAFETY:
714  *  Not Thread Safe - assumes exclusive access to "params"
715  *  (see Thread Safety Definitions in Programmer's Guide)
716  * RETURNS:
717  *  Returns NULL if the function succeeds.
718  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
719  *  Returns a Fatal Error if the function fails in an unrecoverable way.
720  */
721 PKIX_Error *
722 PKIX_ComCRLSelParams_SetMinCRLNumber(
723         PKIX_ComCRLSelParams *params,
724         PKIX_PL_BigInt *number,
725         void *plContext);
726 
727 /*
728  * FUNCTION: PKIX_ComCRLSelParams_SetCrlDp
729  * DESCRIPTION:
730  *
731  * Sets crldp list that can be used to download a crls.
732  *
733  * PARAMETERS:
734  *  "params"
735  *      Address of ComCRLSelParamsParams whose minCRLNumber criterion is to be
736  *      set. Must be non-NULL.
737  *  "crldpList"
738  *      A list of CRLDPs. Can be an emptry list.
739  *  "plContext"
740  *      Platform-specific context pointer.
741  * THREAD SAFETY:
742  *  Not Thread Safe - assumes exclusive access to "params"
743  *  (see Thread Safety Definitions in Programmer's Guide)
744  * RETURNS:
745  *  Returns NULL if the function succeeds.
746  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
747  *  Returns a Fatal Error if the function fails in an unrecoverable way.
748  */
749 PKIX_Error*
750 PKIX_ComCRLSelParams_SetCrlDp(
751          PKIX_ComCRLSelParams *params,
752          PKIX_List *crldpList,
753          void *plContext);
754 
755 #ifdef __cplusplus
756 }
757 #endif
758 
759 #endif /* _PKIX_CRLSEL_H */
760