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_CertSelector and the
6  * PKIX_ComCertSelParams types.
7  *
8  */
9 
10 #ifndef _PKIX_CERTSEL_H
11 #define _PKIX_CERTSEL_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_CertSelector
45  *
46  * PKIX_CertSelectors provide a standard way for the caller to select
47  * certificates based on particular criteria. A CertSelector is typically used
48  * by the caller to specify the constraints they wish to impose on the target
49  * certificate in a chain. (see pkix_params.h) A CertSelector is also often
50  * used to retrieve certificates from a CertStore that match the selector's
51  * criteria. (See pkix_certstore.h) For example, the caller may wish to only
52  * select those certificates that have a particular Subject Distinguished Name
53  * and a particular value for a private certificate extension. The
54  * MatchCallback allows the caller to specify the custom matching logic to be
55  * used by a CertSelector.
56  *
57  * By default, the MatchCallback is set to point to the default implementation
58  * provided by libpkix, which understands how to process the most common
59  * parameters. If the default implementation is used, the caller should set
60  * these common parameters using PKIX_CertSelector_SetCommonCertSelectorParams.
61  * Any common parameter that is not set is assumed to be disabled, which means
62  * the default MatchCallback implementation will select all certificates
63  * without regard to that particular disabled parameter. For example, if the
64  * SerialNumber parameter is not set, MatchCallback will not filter out any
65  * certificate based on its serial number. As such, if no parameters are set,
66  * all are disabled and any certificate will match. If a parameter is
67  * disabled, its associated PKIX_ComCertSelParams_Get* function returns a
68  * default value of NULL, or -1 for PKIX_ComCertSelParams_GetBasicConstraints
69  * and PKIX_ComCertSelParams_GetVersion, or 0 for
70  * PKIX_ComCertSelParams_GetKeyUsage.
71  *
72  * If a custom implementation is desired, the default implementation can be
73  * overridden by calling PKIX_CertSelector_SetMatchCallback. In this case, the
74  * CertSelector can be initialized with a certSelectorContext, which is where
75  * the caller can specify the desired parameters the caller wishes to match
76  * against. Note that this certSelectorContext must be an Object (although any
77  * object type), allowing it to be reference-counted and allowing it to
78  * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
79  * Duplicate).
80  *
81  */
82 
83 /*
84  * FUNCTION: PKIX_CertSelector_MatchCallback
85  * DESCRIPTION:
86  *
87  *  This callback function determines whether the specified Cert pointed to by
88  *  "cert" matches the criteria of the CertSelector pointed to by "selector".
89  *  If the Cert does not matches the CertSelector's criteria, an exception will
90  *  be thrown.
91  *
92  * PARAMETERS:
93  *  "selector"
94  *      Address of CertSelector whose MatchCallback logic and parameters are
95  *      to be used. Must be non-NULL.
96  *  "cert"
97  *      Address of Cert that is to be matched using "selector".
98  *      Must be non-NULL.
99  *  "plContext"
100  *      Platform-specific context pointer.
101  * THREAD SAFETY:
102  *  Thread Safe
103  *
104  *  Multiple threads must be able to safely call this function without
105  *  worrying about conflicts, even if they're operating on the same object.
106  * RETURNS:
107  *  Returns NULL if the function succeeds.
108  *  Returns a CertSelector Error if the function fails in a non-fatal way.
109  *  Returns a Fatal Error if the function fails in an unrecoverable way.
110  */
111 typedef PKIX_Error *
112 (*PKIX_CertSelector_MatchCallback)(
113         PKIX_CertSelector *selector,
114         PKIX_PL_Cert *cert,
115         void *plContext);
116 
117 /*
118  * FUNCTION: PKIX_CertSelector_Create
119  * DESCRIPTION:
120  *
121  *  Creates a new CertSelector using the Object pointed to by
122  *  "certSelectorContext" (if any) and stores it at "pSelector". As noted
123  *  above, by default, the MatchCallback is set to point to the default
124  *  implementation provided by libpkix, which understands how to process
125  *  ComCertSelParams objects. This is overridden if the MatchCallback pointed
126  *  to by "callback" is not NULL, in which case the parameters are specified
127  *  using the certSelectorContext.
128  *
129  * PARAMETERS:
130  *  "callback"
131  *      The MatchCallback function to be used.
132  *  "certSelectorContext"
133  *      Address of Object representing the CertSelector's context (if any).
134  *  "pSelector"
135  *      Address where object pointer will be stored. Must be non-NULL.
136  *  "plContext"
137  *      Platform-specific context pointer.
138  * THREAD SAFETY:
139  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
140  * RETURNS:
141  *  Returns NULL if the function succeeds.
142  *  Returns a CertSelector Error if the function fails in a non-fatal way.
143  *  Returns a Fatal Error if the function fails in an unrecoverable way.
144  */
145 PKIX_Error *
146 PKIX_CertSelector_Create(
147         PKIX_CertSelector_MatchCallback callback,
148         PKIX_PL_Object *certSelectorContext,
149         PKIX_CertSelector **pSelector,
150         void *plContext);
151 
152 /*
153  * FUNCTION: PKIX_CertSelector_GetMatchCallback
154  * DESCRIPTION:
155  *
156  *  Retrieves a pointer to "selector's" Match callback function and puts it in
157  *  "pCallback".
158  *
159  * PARAMETERS:
160  *  "selector"
161  *      The CertSelector whose Match callback is desired. Must be non-NULL.
162  *  "pCallback"
163  *      Address where Match callback function pointer will be stored.
164  *      Must be non-NULL.
165  *  "plContext"
166  *      Platform-specific context pointer.
167  * THREAD SAFETY:
168  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
169  * RETURNS:
170  *  Returns NULL if the function succeeds.
171  *  Returns a CertSelector Error if the function fails in a non-fatal way.
172  *  Returns a Fatal Error if the function fails in an unrecoverable way.
173  */
174 PKIX_Error *
175 PKIX_CertSelector_GetMatchCallback(
176         PKIX_CertSelector *selector,
177         PKIX_CertSelector_MatchCallback *pCallback,
178         void *plContext);
179 
180 /*
181  * FUNCTION: PKIX_CertSelector_GetCertSelectorContext
182  * DESCRIPTION:
183  *
184  *  Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
185  *  of the CertSelector pointed to by "selector" and stores it at
186  *  "pCertSelectorContext".
187  *
188  * PARAMETERS:
189  *  "selector"
190  *      Address of CertSelector whose context is to be stored.
191  *      Must be non-NULL.
192  *  "pCertSelectorContext"
193  *      Address where object pointer will be stored. Must be non-NULL.
194  *  "plContext"
195  *      Platform-specific context pointer.
196  * THREAD SAFETY:
197  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
198  * RETURNS:
199  *  Returns NULL if the function succeeds.
200  *  Returns a CertSelector Error if the function fails in a non-fatal way.
201  *  Returns a Fatal Error if the function fails in an unrecoverable way.
202  */
203 PKIX_Error *
204 PKIX_CertSelector_GetCertSelectorContext(
205         PKIX_CertSelector *selector,
206         PKIX_PL_Object **pCertSelectorContext,
207         void *plContext);
208 
209 /*
210  * FUNCTION: PKIX_CertSelector_GetCommonCertSelectorParams
211  * DESCRIPTION:
212  *
213  *  Retrieves a pointer to the ComCertSelParams object that represent the
214  *  common parameters of the CertSelector pointed to by "selector" and stores
215  *  it at "pCommonCertSelectorParams". If there are no common parameters
216  *  stored with the CertSelector, this function stores NULL at
217  *  "pCommonCertSelectorParams".
218  *
219  * PARAMETERS:
220  *  "selector"
221  *      Address of CertSelector whose ComCertSelParams object is to be stored.
222  *      Must be non-NULL.
223  *  "pCommonCertSelectorParams"
224  *      Address where object pointer will be stored. Must be non-NULL.
225  *  "plContext"
226  *      Platform-specific context pointer.
227  * THREAD SAFETY:
228  *  Conditionally Thread Safe
229  *      (see Thread Safety Definitions in Programmer's Guide)
230  * RETURNS:
231  *  Returns NULL if the function succeeds.
232  *  Returns a CertSelector Error if the function fails in a non-fatal way.
233  *  Returns a Fatal Error if the function fails in an unrecoverable way.
234  */
235 PKIX_Error *
236 PKIX_CertSelector_GetCommonCertSelectorParams(
237         PKIX_CertSelector *selector,
238         PKIX_ComCertSelParams **pCommonCertSelectorParams,
239         void *plContext);
240 
241 /*
242  * FUNCTION: PKIX_CertSelector_SetCommonCertSelectorParams
243  * DESCRIPTION:
244  *
245  *  Sets the common parameters for the CertSelector pointed to by "selector"
246  *  using the ComCertSelParams object pointed to by "commonCertSelectorParams".
247  *
248  * PARAMETERS:
249  *  "selector"
250  *      Address of CertSelector whose common parameters are to be set.
251  *      Must be non-NULL.
252  *  "commonCertSelectorParams"
253  *      Address of ComCertSelParams object representing the common parameters.
254  *  "plContext"
255  *      Platform-specific context pointer.
256  * THREAD SAFETY:
257  *  Not Thread Safe - assumes exclusive access to "selector"
258  *  (see Thread Safety Definitions in Programmer's Guide)
259  * RETURNS:
260  *  Returns NULL if the function succeeds.
261  *  Returns a CertSelector Error if the function fails in a non-fatal way.
262  *  Returns a Fatal Error if the function fails in an unrecoverable way.
263  */
264 PKIX_Error *
265 PKIX_CertSelector_SetCommonCertSelectorParams(
266         PKIX_CertSelector *selector,
267         PKIX_ComCertSelParams *commonCertSelectorParams,
268         void *plContext);
269 
270 /* PKIX_ComCertSelParams
271  *
272  * PKIX_ComCertSelParams objects are X.509 parameters commonly used with
273  * CertSelectors, especially when enforcing constraints on a target
274  * certificate or determining which certificates to retrieve from a CertStore.
275  * ComCertSelParams objects are typically used with those CertSelectors that
276  * use the default implementation of MatchCallback, which understands how to
277  * process ComCertSelParams objects.
278  */
279 
280 /*
281  * FUNCTION: PKIX_ComCertSelParams_Create
282  * DESCRIPTION:
283  *
284  *  Creates a new ComCertSelParams object and stores it at "pParams".
285  *
286  * PARAMETERS:
287  *  "pParams"
288  *      Address where object pointer will be stored. Must be non-NULL.
289  *  "plContext"
290  *      Platform-specific context pointer.
291  * THREAD SAFETY:
292  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
293  * RETURNS:
294  *  Returns NULL if the function succeeds.
295  *  Returns a CertSelector Error if the function fails in a non-fatal way.
296  *  Returns a Fatal Error if the function fails in an unrecoverable way.
297  */
298 PKIX_Error *
299 PKIX_ComCertSelParams_Create(
300         PKIX_ComCertSelParams **pParams,
301         void *plContext);
302 
303 /*
304  * FUNCTION: PKIX_ComCertSelParams_GetSubjAltNames
305  * DESCRIPTION:
306  *
307  *  Retrieves a pointer to the List of GeneralNames (if any) representing the
308  *  subject alternative names criterion that is set in the ComCertSelParams
309  *  object pointed to by "params" and stores it at "pNames". In order to match
310  *  against this criterion, a certificate must contain all or at least one of
311  *  the criterion's subject alternative names (depending on the result of
312  *  PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default behavior
313  *  requires a certificate to contain all of the criterion's subject
314  *  alternative names in order to match.
315  *
316  *  If "params" does not have this criterion set, this function stores NULL at
317  *  "pNames", in which case all certificates are considered to match this
318  *  criterion.
319  *
320  *  Note that the List returned by this function is immutable.
321  *
322  * PARAMETERS:
323  *  "params"
324  *      Address of ComCertSelParams object whose subject alternative names
325  *      criterion (if any) is to be stored. Must be non-NULL.
326  *  "pNames"
327  *      Address where object pointer will be stored. Must be non-NULL.
328  *  "plContext"
329  *      Platform-specific context pointer.
330  * THREAD SAFETY:
331  *  Conditionally Thread Safe
332  *      (see Thread Safety Definitions in Programmer's Guide)
333  * RETURNS:
334  *  Returns NULL if the function succeeds.
335  *  Returns a CertSelector Error if the function fails in a non-fatal way.
336  *  Returns a Fatal Error if the function fails in an unrecoverable way.
337  */
338 PKIX_Error *
339 PKIX_ComCertSelParams_GetSubjAltNames(
340         PKIX_ComCertSelParams *params,
341         PKIX_List **pNames, /* list of PKIX_PL_GeneralName */
342         void *plContext);
343 
344 /*
345  * FUNCTION: PKIX_ComCertSelParams_SetSubjAltNames
346  * DESCRIPTION:
347  *
348  *  Sets the subject alternative names criterion of the ComCertSelParams object
349  *  pointed to by "params" using a List of GeneralNames pointed to by "names".
350  *  In order to match against this criterion, a certificate must contain all or
351  *  at least one of the criterion's subject alternative names (depending on the
352  *  result of PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default
353  *  behavior requires a certificate to contain all of the criterion's subject
354  *  alternative names in order to match.
355  *
356  *  If "names" is NULL, all certificates are considered to match this
357  *  criterion.
358  *
359  * PARAMETERS:
360  *  "params"
361  *      Address of ComCertSelParams object whose subject alternative
362  *      names criterion is to be set. Must be non-NULL.
363  *  "names"
364  *      Address of List of GeneralNames used to set the criterion
365  *      (or NULL to disable the criterion).
366  *  "plContext"
367  *      Platform-specific context pointer.
368  * THREAD SAFETY:
369  *  Not Thread Safe - assumes exclusive access to "params"
370  *  (see Thread Safety Definitions in Programmer's Guide)
371  * RETURNS:
372  *  Returns NULL if the function succeeds.
373  *  Returns a CertSelector 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_ComCertSelParams_SetSubjAltNames(
378         PKIX_ComCertSelParams *params,
379         PKIX_List *names,  /* list of PKIX_PL_GeneralName */
380         void *plContext);
381 
382 /*
383  * FUNCTION: PKIX_ComCertSelParams_AddSubjAltName
384  * DESCRIPTION:
385  *
386  *  Adds to the subject alternative names criterion of the ComCertSelParams
387  *  object pointed to by "params" using the GeneralName pointed to by "name".
388  *  In order to match against this criterion, a certificate must contain all
389  *  or at least one of the criterion's subject alternative names (depending on
390  *  the result of PKIX_ComCertSelParams_GetMatchAllSubjAltNames). The default
391  *  behavior requires a certificate to contain all of the criterion's subject
392  *  alternative names in order to match.
393  *
394  * PARAMETERS:
395  *  "params"
396  *      Address of ComCertSelParams object whose subject alternative names
397  *      criterion is to be added to. Must be non-NULL.
398  *  "name"
399  *      Address of GeneralName to be added.
400  *  "plContext"
401  *      Platform-specific context pointer.
402  * THREAD SAFETY:
403  *  Not Thread Safe - assumes exclusive access to "params"
404  *  (see Thread Safety Definitions in Programmer's Guide)
405  * RETURNS:
406  *  Returns NULL if the function succeeds.
407  *  Returns a CertSelector Error if the function fails in a non-fatal way.
408  *  Returns a Fatal Error if the function fails in an unrecoverable way.
409  */
410 PKIX_Error *
411 PKIX_ComCertSelParams_AddSubjAltName(
412         PKIX_ComCertSelParams *params,
413         PKIX_PL_GeneralName *name,
414         void *plContext);
415 
416 /*
417  * FUNCTION: PKIX_ComCertSelParams_GetPathToNames
418  * DESCRIPTION:
419  *
420  *  Retrieves a pointer to the List of GeneralNames (if any) representing the
421  *  path to names criterion that is set in the ComCertSelParams object pointed
422  *  to by "params" and stores it at "pNames". In order to match against this
423  *  criterion, a certificate must not include name constraints that would
424  *  prohibit building a path to the criterion's specified names.
425  *
426  *  If "params" does not have this criterion set, this function stores NULL at
427  *  "pNames", in which case all certificates are considered to match this
428  *  criterion.
429  *
430  *  Note that the List returned by this function is immutable.
431  *
432  * PARAMETERS:
433  *  "params"
434  *      Address of ComCertSelParams object whose path to names criterion
435  *      (if any) is to be stored. Must be non-NULL.
436  *  "pNames"
437  *      Address where object pointer will be stored. Must be non-NULL.
438  *  "plContext"
439  *      Platform-specific context pointer.
440  * THREAD SAFETY:
441  *  Conditionally Thread Safe
442  *      (see Thread Safety Definitions in Programmer's Guide)
443  * RETURNS:
444  *  Returns NULL if the function succeeds.
445  *  Returns a CertSelector Error if the function fails in a non-fatal way.
446  *  Returns a Fatal Error if the function fails in an unrecoverable way.
447  */
448 PKIX_Error *
449 PKIX_ComCertSelParams_GetPathToNames(
450         PKIX_ComCertSelParams *params,
451         PKIX_List **pNames,  /* list of PKIX_PL_GeneralName */
452         void *plContext);
453 
454 /*
455  * FUNCTION: PKIX_ComCertSelParams_SetPathToNames
456  * DESCRIPTION:
457  *
458  *  Sets the path to names criterion of the ComCertSelParams object pointed to
459  *  by "params" using a List of GeneralNames pointed to by "names". In order to
460  *  match against this criterion, a certificate must not include name
461  *  constraints that would prohibit building a path to the criterion's
462  *  specified names.
463  *
464  *  If "names" is NULL, all certificates are considered to match this
465  *  criterion.
466  *
467  * PARAMETERS:
468  *  "params"
469  *      Address of ComCertSelParams object whose path to names criterion
470  *      is to be set. Must be non-NULL.
471  *  "names"
472  *      Address of List of GeneralNames used to set the criterion
473  *      (or NULL to disable the criterion).
474  *  "plContext"
475  *      Platform-specific context pointer.
476  * THREAD SAFETY:
477  *  Not Thread Safe - assumes exclusive access to "params"
478  *  (see Thread Safety Definitions in Programmer's Guide)
479  * RETURNS:
480  *  Returns NULL if the function succeeds.
481  *  Returns a CertSelector Error if the function fails in a non-fatal way.
482  *  Returns a Fatal Error if the function fails in an unrecoverable way.
483  */
484 PKIX_Error *
485 PKIX_ComCertSelParams_SetPathToNames(
486         PKIX_ComCertSelParams *params,
487         PKIX_List *names,    /* list of PKIX_PL_GeneralName */
488         void *plContext);
489 
490 /*
491  * FUNCTION: PKIX_ComCertSelParams_AddPathToName
492  * DESCRIPTION:
493  *
494  *  Adds to the path to names criterion of the ComCertSelParams object pointed
495  *  to by "params" using the GeneralName pointed to by "pathToName". In order
496  *  to match against this criterion, a certificate must not include name
497  *  constraints that would prohibit building a path to the criterion's
498  *  specified names.
499  *
500  * PARAMETERS:
501  *  "params"
502  *      Address of ComCertSelParams object whose path to names criterion is to
503  *      be added to. Must be non-NULL.
504  *  "pathToName"
505  *      Address of GeneralName to be added.
506  *  "plContext"
507  *      Platform-specific context pointer.
508  * THREAD SAFETY:
509  *  Not Thread Safe - assumes exclusive access to "params"
510  *  (see Thread Safety Definitions in Programmer's Guide)
511  * RETURNS:
512  *  Returns NULL if the function succeeds.
513  *  Returns a CertSelector Error if the function fails in a non-fatal way.
514  *  Returns a Fatal Error if the function fails in an unrecoverable way.
515  */
516 PKIX_Error *
517 PKIX_ComCertSelParams_AddPathToName(
518         PKIX_ComCertSelParams *params,
519         PKIX_PL_GeneralName *pathToName,
520         void *plContext);
521 
522 /*
523  * FUNCTION: PKIX_ComCertSelParams_GetAuthorityKeyIdentifier
524  * DESCRIPTION:
525  *
526  *  Retrieves a pointer to the ByteArray (if any) representing the authority
527  *  key identifier criterion that is set in the ComCertSelParams object
528  *  pointed to by "params" and stores it at "pAuthKeyId". In order to match
529  *  against this criterion, a certificate must contain an
530  *  AuthorityKeyIdentifier extension whose value matches the criterion's
531  *  authority key identifier value.
532  *
533  *  If "params" does not have this criterion set, this function stores NULL at
534  *  "pAuthKeyId", in which case all certificates are considered to match this
535  *  criterion.
536  *
537  * PARAMETERS:
538  *  "params"
539  *      Address of ComCertSelParams object whose authority key identifier
540  *      criterion (if any) is to be stored. Must be non-NULL.
541  *  "pAuthKeyId"
542  *      Address where object pointer will be stored. Must be non-NULL.
543  *  "plContext"
544  *      Platform-specific context pointer.
545  * THREAD SAFETY:
546  *  Conditionally Thread Safe
547  *      (see Thread Safety Definitions in Programmer's Guide)
548  * RETURNS:
549  *  Returns NULL if the function succeeds.
550  *  Returns a CertSelector Error if the function fails in a non-fatal way.
551  *  Returns a Fatal Error if the function fails in an unrecoverable way.
552  */
553 PKIX_Error *
554 PKIX_ComCertSelParams_GetAuthorityKeyIdentifier(
555         PKIX_ComCertSelParams *params,
556         PKIX_PL_ByteArray **pAuthKeyId,
557         void *plContext);
558 
559 /*
560  * FUNCTION: PKIX_ComCertSelParams_SetAuthorityKeyIdentifier
561  * DESCRIPTION:
562  *
563  *  Sets the authority key identifier criterion of the ComCertSelParams object
564  *  pointed to by "params" to the ByteArray pointed to by "authKeyId". In
565  *  order to match against this criterion, a certificate must contain an
566  *  AuthorityKeyIdentifier extension whose value matches the criterion's
567  *  authority key identifier value.
568  *
569  * PARAMETERS:
570  *  "params"
571  *      Address of ComCertSelParams object whose authority key identifier
572  *      criterion is to be set. Must be non-NULL.
573  *  "authKeyId"
574  *      Address of ByteArray used to set the criterion
575  *  "plContext"
576  *      Platform-specific context pointer.
577  * THREAD SAFETY:
578  *  Not Thread Safe - assumes exclusive access to "params"
579  *  (see Thread Safety Definitions in Programmer's Guide)
580  * RETURNS:
581  *  Returns NULL if the function succeeds.
582  *  Returns a CertSelector Error if the function fails in a non-fatal way.
583  *  Returns a Fatal Error if the function fails in an unrecoverable way.
584  */
585 PKIX_Error *
586 PKIX_ComCertSelParams_SetAuthorityKeyIdentifier(
587         PKIX_ComCertSelParams *params,
588         PKIX_PL_ByteArray *authKeyId,
589         void *plContext);
590 
591 /*
592  * FUNCTION: PKIX_ComCertSelParams_GetSubjKeyIdentifier
593  * DESCRIPTION:
594  *
595  *  Retrieves a pointer to the ByteArray (if any) representing the subject key
596  *  identifier criterion that is set in the ComCertSelParams object pointed to
597  *  by "params" and stores it at "pSubjKeyId". In order to match against this
598  *  criterion, a certificate must contain a SubjectKeyIdentifier extension
599  *  whose value matches the criterion's subject key identifier value.
600  *
601  *  If "params" does not have this criterion set, this function stores NULL at
602  *  "pSubjKeyId", in which case all certificates are considered to match this
603  *  criterion.
604  *
605  * PARAMETERS:
606  *  "params"
607  *      Address of ComCertSelParams object whose subject key identifier
608  *      criterion (if any) is to be stored. Must be non-NULL.
609  *  "pSubjKeyId"
610  *      Address where object pointer will be stored. Must be non-NULL.
611  *  "plContext"
612  *      Platform-specific context pointer.
613  * THREAD SAFETY:
614  *  Conditionally Thread Safe
615  *      (see Thread Safety Definitions in Programmer's Guide)
616  * RETURNS:
617  *  Returns NULL if the function succeeds.
618  *  Returns a CertSelector Error if the function fails in a non-fatal way.
619  *  Returns a Fatal Error if the function fails in an unrecoverable way.
620  */
621 PKIX_Error *
622 PKIX_ComCertSelParams_GetSubjKeyIdentifier(
623         PKIX_ComCertSelParams *params,
624         PKIX_PL_ByteArray **pSubjKeyId,
625         void *plContext);
626 
627 /*
628  * FUNCTION: PKIX_ComCertSelParams_SetSubjKeyIdentifier
629  * DESCRIPTION:
630  *
631  *  Sets the subject key identifier criterion of the ComCertSelParams object
632  *  pointed to by "params" using a ByteArray pointed to by "subjKeyId". In
633  *  order to match against this criterion, a certificate must contain an
634  *  SubjectKeyIdentifier extension whose value matches the criterion's subject
635  *  key identifier value.
636  *
637  * PARAMETERS:
638  *  "params"
639  *      Address of ComCertSelParams object whose subject key identifier
640  *      criterion is to be set. Must be non-NULL.
641  *  "subjKeyId"
642  *      Address of ByteArray used to set the criterion
643  *  "plContext"
644  *      Platform-specific context pointer.
645  * THREAD SAFETY:
646  *  Not Thread Safe - assumes exclusive access to "params"
647  *  (see Thread Safety Definitions in Programmer's Guide)
648  * RETURNS:
649  *  Returns NULL if the function succeeds.
650  *  Returns a CertSelector Error if the function fails in a non-fatal way.
651  *  Returns a Fatal Error if the function fails in an unrecoverable way.
652  */
653 PKIX_Error *
654 PKIX_ComCertSelParams_SetSubjKeyIdentifier(
655         PKIX_ComCertSelParams *params,
656         PKIX_PL_ByteArray *subKeyId,
657         void *plContext);
658 
659 /*
660  * FUNCTION: PKIX_ComCertSelParams_GetSubjPubKey
661  * DESCRIPTION:
662  *
663  *  Retrieves a pointer to the PublicKey (if any) representing the subject
664  *  public key criterion that is set in the ComCertSelParams object pointed to
665  *  by "params" and stores it at "pPubKey". In order to match against this
666  *  criterion, a certificate must contain a SubjectPublicKey that matches the
667  *  criterion's public key.
668  *
669  *  If "params" does not have this criterion set, this function stores NULL at
670  *  "pPubKey", in which case all certificates are considered to match this
671  *  criterion.
672  *
673  * PARAMETERS:
674  *  "params"
675  *      Address of ComCertSelParams object whose subject public key criterion
676  *      (if any) is to be stored. Must be non-NULL.
677  *  "pPubKey"
678  *      Address where object pointer will be stored. Must be non-NULL.
679  *  "plContext"
680  *      Platform-specific context pointer.
681  * THREAD SAFETY:
682  *  Conditionally Thread Safe
683  *      (see Thread Safety Definitions in Programmer's Guide)
684  * RETURNS:
685  *  Returns NULL if the function succeeds.
686  *  Returns a CertSelector Error if the function fails in a non-fatal way.
687  *  Returns a Fatal Error if the function fails in an unrecoverable way.
688  */
689 PKIX_Error *
690 PKIX_ComCertSelParams_GetSubjPubKey(
691         PKIX_ComCertSelParams *params,
692         PKIX_PL_PublicKey **pPubKey,
693         void *plContext);
694 
695 /*
696  * FUNCTION: PKIX_ComCertSelParams_SetSubjPubKey
697  * DESCRIPTION:
698  *
699  *  Sets the subject public key criterion of the ComCertSelParams object
700  *  pointed to by "params" using a PublicKey pointed to by "pubKey". In order
701  *  to match against this criterion, a certificate must contain a
702  *  SubjectPublicKey that matches the criterion's public key.
703  *
704  * PARAMETERS:
705  *  "params"
706  *      Address of ComCertSelParams object whose subject public key
707  *      criterion is to be set. Must be non-NULL.
708  *  "pubKey"
709  *      Address of PublicKey used to set the criterion
710  *  "plContext"
711  *      Platform-specific context pointer.
712  * THREAD SAFETY:
713  *  Not Thread Safe - assumes exclusive access to "params"
714  *  (see Thread Safety Definitions in Programmer's Guide)
715  * RETURNS:
716  *  Returns NULL if the function succeeds.
717  *  Returns a CertSelector Error if the function fails in a non-fatal way.
718  *  Returns a Fatal Error if the function fails in an unrecoverable way.
719  */
720 PKIX_Error *
721 PKIX_ComCertSelParams_SetSubjPubKey(
722         PKIX_ComCertSelParams *params,
723         PKIX_PL_PublicKey *pubKey,
724         void *plContext);
725 
726 /*
727  * FUNCTION: PKIX_ComCertSelParams_GetSubjPKAlgId
728  * DESCRIPTION:
729  *
730  *  Retrieves a pointer to the OID (if any) representing the subject public key
731  *  algorithm identifier criterion that is set in the ComCertSelParams object
732  *  pointed to by "params" and stores it at "pPubKey". In order to match
733  *  against this criterion, a certificate must contain a SubjectPublicKey with
734  *  an algorithm that matches the criterion's algorithm.
735  *
736  *  If "params" does not have this criterion set, this function stores NULL at
737  *  "pAlgId", in which case all certificates are considered to match this
738  *  criterion.
739  *
740  * PARAMETERS:
741  *  "params"
742  *      Address of ComCertSelParams object whose subject public key algorithm
743  *      identifier (if any) is to be stored. Must be non-NULL.
744  *  "pAlgId"
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 CertSelector 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_ComCertSelParams_GetSubjPKAlgId(
758         PKIX_ComCertSelParams *params,
759         PKIX_PL_OID **pAlgId,
760         void *plContext);
761 
762 /*
763  * FUNCTION: PKIX_ComCertSelParams_SetSubjPKAlgId
764  * DESCRIPTION:
765  *
766  *  Sets the subject public key algorithm identifier criterion of the
767  *  ComCertSelParams object pointed to by "params" using an OID pointed to by
768  *  "algId". In order to match against this criterion, a certificate must
769  *  contain a SubjectPublicKey with an algorithm that matches the criterion's
770  *  algorithm.
771  *
772  *  If "algId" is NULL, all certificates are considered to match this
773  *  criterion.
774  *
775  * PARAMETERS:
776  *  "params"
777  *      Address of ComCertSelParams object whose subject public key
778  *      algorithm identifier criterion is to be set. Must be non-NULL.
779  *  "algId"
780  *      Address of OID used to set criterion
781  *      (or NULL to disable the criterion).
782  *  "plContext"
783  *      Platform-specific context pointer.
784  * THREAD SAFETY:
785  *  Not Thread Safe - assumes exclusive access to "params"
786  *  (see Thread Safety Definitions in Programmer's Guide)
787  * RETURNS:
788  *  Returns NULL if the function succeeds.
789  *  Returns a CertSelector Error if the function fails in a non-fatal way.
790  *  Returns a Fatal Error if the function fails in an unrecoverable way.
791  */
792 PKIX_Error *
793 PKIX_ComCertSelParams_SetSubjPKAlgId(
794         PKIX_ComCertSelParams *params,
795         PKIX_PL_OID *algId,
796         void *plContext);
797 
798 /*
799  * FUNCTION: PKIX_ComCertSelParams_GetBasicConstraints
800  * DESCRIPTION:
801  *
802  *  Retrieves a pointer to the minimum path length (if any) representing the
803  *  basic constraints criterion that is set in the ComCertSelParams object
804  *  pointed to by "params" and stores it at "pMinPathLength". In order to
805  *  match against this criterion, there are several possibilities.
806  *
807  *  1) If the criterion's minimum path length is greater than or equal to zero,
808  *  a certificate must include a BasicConstraints extension with a pathLen of
809  *  at least this value.
810  *
811  *  2) If the criterion's minimum path length is -2, a certificate must be an
812  *  end-entity certificate.
813  *
814  *  3) If the criterion's minimum path length is -1, no basic constraints check
815  *  is done and all certificates are considered to match this criterion.
816  *
817  *  The semantics of other values of the criterion's minimum path length are
818  *  undefined but may be defined in future versions of the API.
819  *
820  *  If "params" does not have this criterion set, this function stores -1 at
821  *  "pMinPathLength", in which case all certificates are considered to match
822  *  this criterion.
823  *
824  * PARAMETERS:
825  *  "params"
826  *      Address of ComCertSelParams object whose basic constraints criterion
827  *      (if any) is to be stored. Must be non-NULL.
828  *  "pMinPathLength"
829  *      Address where PKIX_Int32 will be stored. Must be non-NULL.
830  *  "plContext"
831  *      Platform-specific context pointer.
832  * THREAD SAFETY:
833  *  Conditionally Thread Safe
834  *      (see Thread Safety Definitions in Programmer's Guide)
835  * RETURNS:
836  *  Returns NULL if the function succeeds.
837  *  Returns a CertSelector Error if the function fails in a non-fatal way.
838  *  Returns a Fatal Error if the function fails in an unrecoverable way.
839  */
840 PKIX_Error *
841 PKIX_ComCertSelParams_GetBasicConstraints(
842         PKIX_ComCertSelParams *params,
843         PKIX_Int32 *pMinPathLength,
844         void *plContext);
845 
846 /*
847  * FUNCTION: PKIX_ComCertSelParams_SetBasicConstraints
848  * DESCRIPTION:
849  *
850  *  Sets the basic constraints criterion of the ComCertSelParams object
851  *  pointed to by "params" using the integer value of "minPathLength". In
852  *  order to match against this criterion, there are several possibilities.
853  *
854  *  1) If the criterion's minimum path length is greater than or equal to zero,
855  *  a certificate must include a BasicConstraints extension with a pathLen of
856  *  at least this value.
857  *
858  *  2) If the criterion's minimum path length is -2, a certificate must be an
859  *  end-entity certificate.
860  *
861  *  3) If the criterion's minimum path length is -1, no basic constraints check
862  *  is done and all certificates are considered to match this criterion.
863  *
864  *  The semantics of other values of the criterion's minimum path length are
865  *  undefined but may be defined in future versions of the API.
866  *
867  * PARAMETERS:
868  *  "params"
869  *      Address of ComCertSelParams object whose basic constraints
870  *      criterion is to be set. Must be non-NULL.
871  *  "minPathLength"
872  *      Value of PKIX_Int32 used to set the criterion
873  *      (or -1 to disable the criterion).
874  *  "plContext"
875  *      Platform-specific context pointer.
876  * THREAD SAFETY:
877  *  Not Thread Safe - assumes exclusive access to "params"
878  *  (see Thread Safety Definitions in Programmer's Guide)
879  * RETURNS:
880  *  Returns NULL if the function succeeds.
881  *  Returns a CertSelector Error if the function fails in a non-fatal way.
882  *  Returns a Fatal Error if the function fails in an unrecoverable way.
883  */
884 PKIX_Error *
885 PKIX_ComCertSelParams_SetBasicConstraints(
886         PKIX_ComCertSelParams *params,
887         PKIX_Int32 minPathLength,
888         void *plContext);
889 
890 /*
891  * FUNCTION: PKIX_ComCertSelParams_GetCertificate
892  * DESCRIPTION:
893  *
894  *  Retrieves a pointer to the Cert (if any) representing the certificate
895  *  criterion that is set in the ComCertSelParams object pointed to by
896  *  "params" and stores it at "pCert". In order to match against this
897  *  criterion, a certificate must be equal to the criterion's certificate. If
898  *  this criterion is specified, it is usually not necessary to specify any
899  *  other criteria, since this criterion requires an exact certificate match.
900  *
901  *  If "params" does not have this criterion set, this function stores NULL at
902  *  "pCert", in which case all certificates are considered to match this
903  *  criterion.
904  *
905  * PARAMETERS:
906  *  "params"
907  *      Address of ComCertSelParams object whose certificate criterion
908  *      (if any) is to be stored. Must be non-NULL.
909  *  "pCert"
910  *      Address where object pointer will be stored. Must be non-NULL.
911  *  "plContext"
912  *      Platform-specific context pointer.
913  * THREAD SAFETY:
914  *  Conditionally Thread Safe
915  *      (see Thread Safety Definitions in Programmer's Guide)
916  * RETURNS:
917  *  Returns NULL if the function succeeds.
918  *  Returns a CertSelector Error if the function fails in a non-fatal way.
919  *  Returns a Fatal Error if the function fails in an unrecoverable way.
920  */
921 PKIX_Error *
922 PKIX_ComCertSelParams_GetCertificate(
923         PKIX_ComCertSelParams *params,
924         PKIX_PL_Cert **pCert,
925         void *plContext);
926 
927 /*
928  * FUNCTION: PKIX_ComCertSelParams_SetCertificate
929  * DESCRIPTION:
930  *
931  *  Sets the certificate criterion of the ComCertSelParams object pointed to by
932  * "params" using a Cert pointed to by "cert". In order to match against this
933  *  criterion, a certificate must be equal to the criterion's certificate.
934  *  If this criterion is specified, it is usually not necessary to specify
935  *  any other criteria, since this criterion requires an exact certificate
936  *  match.
937  *
938  *  If "cert" is NULL, all certificates are considered to match this criterion.
939  *
940  * PARAMETERS:
941  *  "params"
942  *      Address of ComCertSelParams object whose certificate criterion is to be
943  *      set. Must be non-NULL.
944  *  "cert"
945  *      Address of Cert used to set the criterion
946  *      (or NULL to disable the criterion).
947  *  "plContext"
948  *      Platform-specific context pointer.
949  * THREAD SAFETY:
950  *  Not Thread Safe - assumes exclusive access to "params"
951  *  (see Thread Safety Definitions in Programmer's Guide)
952  * RETURNS:
953  *  Returns NULL if the function succeeds.
954  *  Returns a CertSelector Error if the function fails in a non-fatal way.
955  *  Returns a Fatal Error if the function fails in an unrecoverable way.
956  */
957 PKIX_Error *
958 PKIX_ComCertSelParams_SetCertificate(
959         PKIX_ComCertSelParams *params,
960         PKIX_PL_Cert *cert,
961         void *plContext);
962 
963 /*
964  * FUNCTION: PKIX_ComCertSelParams_GetCertificateValid
965  * DESCRIPTION:
966  *
967  *  Retrieves a pointer to the Date (if any) representing the certificate
968  *  validity criterion that is set in the ComCertSelParams object pointed to by
969  *  "params" and stores it at "pDate". In order to match against this
970  *  criterion, a certificate's validity period must include the criterion's
971  *  Date.
972  *
973  *  If "params" does not have this criterion set, this function stores NULL at
974  *  "pDate", in which case all certificates are considered to match this
975  *  criterion.
976  *
977  * PARAMETERS:
978  *  "params"
979  *      Address of ComCertSelParams object whose certificate validity criterion
980  *      (if any) is to be stored. Must be non-NULL.
981  *  "pDate"
982  *      Address where object pointer will be stored. Must be non-NULL.
983  *  "plContext"
984  *      Platform-specific context pointer.
985  * THREAD SAFETY:
986  *  Conditionally Thread Safe
987  *      (see Thread Safety Definitions in Programmer's Guide)
988  * RETURNS:
989  *  Returns NULL if the function succeeds.
990  *  Returns a CertSelector Error if the function fails in a non-fatal way.
991  *  Returns a Fatal Error if the function fails in an unrecoverable way.
992  */
993 PKIX_Error *
994 PKIX_ComCertSelParams_GetCertificateValid(
995         PKIX_ComCertSelParams *params,
996         PKIX_PL_Date **pDate,
997         void *plContext);
998 
999 /*
1000  * FUNCTION: PKIX_ComCertSelParams_SetCertificateValid
1001  * DESCRIPTION:
1002  *
1003  *  Sets the certificate validity criterion of the ComCertSelParams object
1004  *  pointed to by "params" using a Date pointed to by "date". In order to
1005  *  match against this criterion, a certificate's validity period must include
1006  *  the criterion's Date.
1007  *
1008  *  If "date" is NULL, all certificates are considered to match this criterion.
1009  *
1010  * PARAMETERS:
1011  *  "params"
1012  *      Address of ComCertSelParams object whose certificate validity criterion
1013  *      is to be set. Must be non-NULL.
1014  *  "date"
1015  *      Address of Date used to set the criterion
1016  *      (or NULL to disable the criterion).
1017  *  "plContext"
1018  *      Platform-specific context pointer.
1019  * THREAD SAFETY:
1020  *  Not Thread Safe - assumes exclusive access to "params"
1021  *  (see Thread Safety Definitions in Programmer's Guide)
1022  * RETURNS:
1023  *  Returns NULL if the function succeeds.
1024  *  Returns a CertSelector 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_ComCertSelParams_SetCertificateValid(
1029         PKIX_ComCertSelParams *params,
1030         PKIX_PL_Date *date,
1031         void *plContext);
1032 
1033 /*
1034  * FUNCTION: PKIX_ComCertSelParams_GetSerialNumber
1035  * DESCRIPTION:
1036  *
1037  *  Retrieves a pointer to the BigInt (if any) representing the serial number
1038  *  criterion that is set in the ComCertSelParams object pointed to by
1039  *  "params" and stores it at "pSerialNumber". In order to match against this
1040  *  criterion, a certificate must have a serial number equal to the
1041  *  criterion's serial number.
1042  *
1043  *  If "params" does not have this criterion set, this function stores NULL at
1044  *  "pSerialNumber", in which case all certificates are considered to match
1045  *  this criterion.
1046  *
1047  * PARAMETERS:
1048  *  "params"
1049  *      Address of ComCertSelParams object whose serial number criterion
1050  *      (if any) is to be stored. Must be non-NULL.
1051  *  "pSerialNumber"
1052  *      Address where object pointer will be stored. Must be non-NULL.
1053  *  "plContext"
1054  *      Platform-specific context pointer.
1055  * THREAD SAFETY:
1056  *  Conditionally Thread Safe
1057  *      (see Thread Safety Definitions in Programmer's Guide)
1058  * RETURNS:
1059  *  Returns NULL if the function succeeds.
1060  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1061  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1062  */
1063 PKIX_Error *
1064 PKIX_ComCertSelParams_GetSerialNumber(
1065         PKIX_ComCertSelParams *params,
1066         PKIX_PL_BigInt **pSerialNumber,
1067         void *plContext);
1068 
1069 /*
1070  * FUNCTION: PKIX_ComCertSelParams_SetSerialNumber
1071  * DESCRIPTION:
1072  *
1073  *  Sets the serial number criterion of the ComCertSelParams object pointed to
1074  *  by "params" using a BigInt pointed to by "serialNumber". In order to match
1075  *  against this criterion, a certificate must have a serial number equal to
1076  *  the criterion's serial number.
1077  *
1078  *  If "serialNumber" is NULL, all certificates are considered to match this
1079  *  criterion.
1080  *
1081  * PARAMETERS:
1082  *  "params"
1083  *      Address of ComCertSelParams object whose serial number criterion is to
1084  *      be set. Must be non-NULL.
1085  *  "serialNumber"
1086  *      Address of BigInt used to set the criterion
1087  *      (or NULL to disable the criterion).
1088  *  "plContext"
1089  *      Platform-specific context pointer.
1090  * THREAD SAFETY:
1091  *  Not Thread Safe - assumes exclusive access to "params"
1092  *  (see Thread Safety Definitions in Programmer's Guide)
1093  * RETURNS:
1094  *  Returns NULL if the function succeeds.
1095  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1096  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1097  */
1098 PKIX_Error *
1099 PKIX_ComCertSelParams_SetSerialNumber(
1100         PKIX_ComCertSelParams *params,
1101         PKIX_PL_BigInt *serialNumber,
1102         void *plContext);
1103 
1104 /*
1105  * FUNCTION: PKIX_ComCertSelParams_GetVersion
1106  * DESCRIPTION:
1107  *
1108  *  Retrieves a PKIX_UInt32 (if any) representing the version criterion that is
1109  *  set in the ComCertSelParams object pointed to by "params" and stores it at
1110  *  "pVersion". In order to match against this criterion, a certificate's
1111  *  version must be equal to the criterion's version.
1112  *
1113  *  The version number will either be 0, 1, or 2 (corresponding to
1114  *  v1, v2, or v3, respectively).
1115  *
1116  *  If "params" does not have this criterion set, this function stores
1117  *  0xFFFFFFFF at "pVersion", in which case all certificates are considered
1118  *  to match this criterion.
1119  *
1120  * PARAMETERS:
1121  *  "params"
1122  *      Address of ComCertSelParams object whose version criterion (if any) is
1123  *      to be stored. Must be non-NULL.
1124  *  "pVersion"
1125  *      Address where PKIX_Int32 will be stored. Must be non-NULL.
1126  *  "plContext"
1127  *      Platform-specific context pointer.
1128  * THREAD SAFETY:
1129  *  Conditionally Thread Safe
1130  *      (see Thread Safety Definitions in Programmer's Guide)
1131  * RETURNS:
1132  *  Returns NULL if the function succeeds.
1133  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1134  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1135  */
1136 PKIX_Error *
1137 PKIX_ComCertSelParams_GetVersion(
1138         PKIX_ComCertSelParams *params,
1139         PKIX_UInt32 *pVersion,
1140         void *plContext);
1141 
1142 /*
1143  * FUNCTION: PKIX_ComCertSelParams_SetVersion
1144  * DESCRIPTION:
1145  *
1146  *  Sets the version criterion of the ComCertSelParams object pointed to by
1147  *  "params" using the integer value of "version". In order to match against
1148  *  this criterion, a certificate's version must be equal to the criterion's
1149  *  version. If the criterion's version is -1, no version check is done and
1150  *  all certificates are considered to match this criterion.
1151  *
1152  * PARAMETERS:
1153  *  "params"
1154  *      Address of ComCertSelParams object whose version criterion is to be
1155  *      set. Must be non-NULL.
1156  *  "version"
1157  *      Value of PKIX_Int32 used to set the criterion
1158  *      (or -1 to disable the criterion).
1159  *  "plContext"
1160  *      Platform-specific context pointer.
1161  * THREAD SAFETY:
1162  *  Not Thread Safe - assumes exclusive access to "params"
1163  *  (see Thread Safety Definitions in Programmer's Guide)
1164  * RETURNS:
1165  *  Returns NULL if the function succeeds.
1166  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1167  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1168  */
1169 PKIX_Error *
1170 PKIX_ComCertSelParams_SetVersion(
1171         PKIX_ComCertSelParams *params,
1172         PKIX_Int32 version,
1173         void *plContext);
1174 
1175 
1176 /*
1177  * FUNCTION: PKIX_ComCertSelParams_GetKeyUsage
1178  * DESCRIPTION:
1179  *
1180  *  Retrieves a PKIX_UInt32 (if any) representing the key usage criterion that
1181  *  is set in the ComCertSelParams object pointed to by "params" and stores it
1182  *  at "pKeyUsage". In order to match against this criterion, a certificate
1183  *  must allow the criterion's key usage values. Note that a certificate that
1184  *  has no KeyUsage extension implicity allows all key usages. Note also that
1185  *  this functions supports a maximum of 32 key usage bits.
1186  *
1187  *  If "params" does not have this criterion set, this function stores zero at
1188  *  "pKeyUsage", in which case all certificates are considered to match this
1189  *  criterion.
1190  *
1191  * PARAMETERS:
1192  *  "params"
1193  *      Address of ComCertSelParams object whose key usage criterion (if any)
1194  *      is to be stored. Must be non-NULL.
1195  *  "pKeyUsage"
1196  *      Address where PKIX_UInt32 will be stored. Must not be non-NULL.
1197  *  "plContext"
1198  *      Platform-specific context pointer.
1199  * THREAD SAFETY:
1200  *  Conditionally Thread Safe
1201  *      (see Thread Safety Definitions in Programmer's Guide)
1202  * RETURNS:
1203  *  Returns NULL if the function succeeds.
1204  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1205  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1206  */
1207 PKIX_Error *
1208 PKIX_ComCertSelParams_GetKeyUsage(
1209         PKIX_ComCertSelParams *params,
1210         PKIX_UInt32 *pKeyUsage,
1211         void *plContext);
1212 
1213 /*
1214  * FUNCTION: PKIX_ComCertSelParams_SetKeyUsage
1215  * DESCRIPTION:
1216  *
1217  *  Sets the key usage criterion of the ComCertSelParams object pointed to by
1218  *  "params" using the integer value of "keyUsage". In order to match against
1219  *  this criterion, a certificate must allow the criterion's key usage values.
1220  *  Note that a certificate that has no KeyUsage extension implicity allows
1221  *  all key usages. Note also that this functions supports a maximum of 32 key
1222  *  usage bits.
1223  *
1224  *  If the criterion's key usage value is zero, no key usage check is done and
1225  *  all certificates are considered to match this criterion.
1226  *
1227  * PARAMETERS:
1228  *  "params"
1229  *      Address of ComCertSelParams object whose key usage criterion is to be
1230  *      set. Must be non-NULL.
1231  *  "keyUsage"
1232  *      Value of PKIX_Int32 used to set the criterion
1233  *      (or zero to disable the criterion).
1234  *  "plContext"
1235  *      Platform-specific context pointer.
1236  * THREAD SAFETY:
1237  *  Not Thread Safe - assumes exclusive access to "params"
1238  *  (see Thread Safety Definitions in Programmer's Guide)
1239  * RETURNS:
1240  *  Returns NULL if the function succeeds.
1241  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1242  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1243  */
1244 PKIX_Error *
1245 PKIX_ComCertSelParams_SetKeyUsage(
1246         PKIX_ComCertSelParams *params,
1247         PKIX_UInt32 keyUsage,
1248         void *plContext);
1249 
1250 /*
1251  * FUNCTION: PKIX_ComCertSelParams_GetExtendedKeyUsage
1252  * DESCRIPTION:
1253  *
1254  *  Retrieves a pointer to the List of OIDs (if any) representing the extended
1255  *  key usage criterion that is set in the ComCertSelParams object pointed to
1256  *  by "params" and stores it at "pExtKeyUsage". In order to match against this
1257  *  criterion, a certificate's ExtendedKeyUsage extension must allow the
1258  *  criterion's extended key usages. Note that a certificate that has no
1259  *  ExtendedKeyUsage extension implicity allows all key purposes.
1260  *
1261  *  If "params" does not have this criterion set, this function stores NULL at
1262  *  "pExtKeyUsage", in which case all certificates are considered to match
1263  *  this criterion.
1264  *
1265  *  Note that the List returned by this function is immutable.
1266  *
1267  * PARAMETERS:
1268  *  "params"
1269  *      Address of ComCertSelParams object whose extended key usage criterion
1270  *      (if any) is to be stored. Must be non-NULL.
1271  *  "pExtKeyUsage"
1272  *      Address where object pointer will be stored. Must be non-NULL.
1273  *  "plContext"
1274  *      Platform-specific context pointer.
1275  * THREAD SAFETY:
1276  *  Conditionally Thread Safe
1277  *      (see Thread Safety Definitions in Programmer's Guide)
1278  * RETURNS:
1279  *  Returns NULL if the function succeeds.
1280  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1281  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1282  */
1283 PKIX_Error *
1284 PKIX_ComCertSelParams_GetExtendedKeyUsage(
1285         PKIX_ComCertSelParams *params,
1286         PKIX_List **pExtKeyUsage, /* list of PKIX_PL_OID */
1287         void *plContext);
1288 
1289 /*
1290  * FUNCTION: PKIX_ComCertSelParams_SetExtendedKeyUsage
1291  * DESCRIPTION:
1292  *
1293  *  Sets the extended key usage criterion of the ComCertSelParams object
1294  *  pointed to by "params" using a List of OIDs pointed to by "extKeyUsage".
1295  *  In order to match against this criterion, a certificate's ExtendedKeyUsage
1296  *  extension must allow the criterion's extended key usages. Note that a
1297  *  certificate that has no ExtendedKeyUsage extension implicitly allows all
1298  *  key purposes.
1299  *
1300  *  If "extKeyUsage" is NULL, all certificates are considered to match this
1301  *  criterion.
1302  *
1303  * PARAMETERS:
1304  *  "params"
1305  *      Address of ComCertSelParams object whose extended key usage criterion
1306  *      is to be set. Must be non-NULL.
1307  *  "extKeyUsage"
1308  *      Address of List of OIDs used to set the criterion
1309  *      (or NULL to disable the criterion).
1310  *  "plContext"
1311  *      Platform-specific context pointer.
1312  * THREAD SAFETY:
1313  *  Not Thread Safe - assumes exclusive access to "params"
1314  *  (see Thread Safety Definitions in Programmer's Guide)
1315  * RETURNS:
1316  *  Returns NULL if the function succeeds.
1317  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1318  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1319  */
1320 PKIX_Error *
1321 PKIX_ComCertSelParams_SetExtendedKeyUsage(
1322         PKIX_ComCertSelParams *params,
1323         PKIX_List *extKeyUsage,  /* list of PKIX_PL_OID */
1324         void *plContext);
1325 
1326 /*
1327  * FUNCTION: PKIX_ComCertSelParams_GetPolicy
1328  * DESCRIPTION:
1329  *
1330  *  Retrieves a pointer to the List of OIDs (if any) representing the policy
1331  *  criterion that is set in the ComCertSelParams object pointed to by
1332  *  "params" and stores it at "pPolicy". In order to match against this
1333  *  criterion, a certificate's CertificatePolicies extension must include at
1334  *  least one of the criterion's policies. If "params" has this criterion set,
1335  *  but the List of OIDs is empty, then a certificate's CertificatePolicies
1336  *  extension must include at least some policy.
1337  *
1338  *  If "params" does not have this criterion set, this function stores NULL at
1339  *  "pPolicy", in which case all certificates are considered to match this
1340  *  criterion.
1341  *
1342  *  Note that the List returned by this function is immutable.
1343  *
1344  * PARAMETERS:
1345  *  "params"
1346  *      Address of ComCertSelParams object whose policy criterion (if any) is
1347  *      to be stored. Must be non-NULL.
1348  *  "pPolicy"
1349  *      Address where object pointer will be stored. Must be non-NULL.
1350  *  "plContext"
1351  *      Platform-specific context pointer.
1352  * THREAD SAFETY:
1353  *  Conditionally Thread Safe
1354  *      (see Thread Safety Definitions in Programmer's Guide)
1355  * RETURNS:
1356  *  Returns NULL if the function succeeds.
1357  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1358  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1359  */
1360 PKIX_Error *
1361 PKIX_ComCertSelParams_GetPolicy(
1362         PKIX_ComCertSelParams *params,
1363         PKIX_List **pPolicy,  /* list of PKIX_PL_OID */
1364         void *plContext);
1365 
1366 /*
1367  * FUNCTION: PKIX_ComCertSelParams_SetPolicy
1368  * DESCRIPTION:
1369  *
1370  *  Sets the policy criterion of the ComCertSelParams object pointed to by
1371  *  "params" using a List of OIDs pointed to by "policy". In order to match
1372  *  against this criterion, a certificate's CertificatePolicies extension must
1373  *  include at least one of the criterion's policies. If "params" has this
1374  *  criterion set, but the List of OIDs is empty, then a certificate's
1375  *  CertificatePolicies extension must include at least some policy.
1376  *
1377  *  If "policy" is NULL, all certificates are considered to match this
1378  *  criterion.
1379  *
1380  * PARAMETERS:
1381  *  "params"
1382  *      Address of ComCertSelParams object whose policy criterion is to be set.
1383  *      Must be non-NULL.
1384  *  "policy"
1385  *      Address of List of OIDs used to set the criterion
1386  *      (or NULL to disable the criterion).
1387  *  "plContext"
1388  *      Platform-specific context pointer.
1389  * THREAD SAFETY:
1390  *  Not Thread Safe - assumes exclusive access to "params"
1391  *  (see Thread Safety Definitions in Programmer's Guide)
1392  * RETURNS:
1393  *  Returns NULL if the function succeeds.
1394  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1395  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1396  */
1397 PKIX_Error *
1398 PKIX_ComCertSelParams_SetPolicy(
1399         PKIX_ComCertSelParams *params,
1400         PKIX_List *policy,    /* list of PKIX_PL_OID */
1401         void *plContext);
1402 
1403 /*
1404  * FUNCTION: PKIX_ComCertSelParams_GetIssuer
1405  * DESCRIPTION:
1406  *
1407  *  Retrieves a pointer to the X500Name (if any) representing the issuer
1408  *  criterion that is set in the ComCertSelParams object pointed to by
1409  *  "params" and stores it at "pIssuer". In order to match against this
1410  *  criterion, a certificate's IssuerName must match the criterion's issuer
1411  *  name.
1412  *
1413  *  If "params" does not have this criterion set, this function stores NULL at
1414  *  "pIssuer", in which case all certificates are considered to match this
1415  *  criterion.
1416  *
1417  * PARAMETERS:
1418  *  "params"
1419  *      Address of ComCertSelParams object whose issuer criterion (if any) is
1420  *      to be stored. Must be non-NULL.
1421  *  "pIssuer"
1422  *      Address where object pointer will be stored. Must be non-NULL.
1423  *  "plContext"
1424  *      Platform-specific context pointer.
1425  * THREAD SAFETY:
1426  *  Conditionally Thread Safe
1427  *      (see Thread Safety Definitions in Programmer's Guide)
1428  * RETURNS:
1429  *  Returns NULL if the function succeeds.
1430  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1431  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1432  */
1433 PKIX_Error *
1434 PKIX_ComCertSelParams_GetIssuer(
1435         PKIX_ComCertSelParams *params,
1436         PKIX_PL_X500Name **pIssuer,
1437         void *plContext);
1438 
1439 /*
1440  * FUNCTION: PKIX_ComCertSelParams_SetIssuer
1441  * DESCRIPTION:
1442  *
1443  *  Sets the issuer criterion of the ComCertSelParams object pointed to by
1444  *  "params" using an X500Name pointed to by "issuer". In order to match
1445  *  against this criterion, a certificate's IssuerName must match the
1446  *  criterion's issuer name.
1447  *
1448  *  If "issuer" is NULL, all certificates are considered to match this
1449  *  criterion.
1450  *
1451  * PARAMETERS:
1452  *  "params"
1453  *      Address of ComCertSelParams object whose issuer criterion is to be set.
1454  *      Must be non-NULL.
1455  *  "issuer"
1456  *      Address of X500Name used to set the criterion
1457  *      (or NULL to disable the criterion).
1458  *  "plContext"
1459  *      Platform-specific context pointer.
1460  * THREAD SAFETY:
1461  *  Not Thread Safe - assumes exclusive access to "params"
1462  *  (see Thread Safety Definitions in Programmer's Guide)
1463  * RETURNS:
1464  *  Returns NULL if the function succeeds.
1465  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1466  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1467  */
1468 PKIX_Error *
1469 PKIX_ComCertSelParams_SetIssuer(
1470         PKIX_ComCertSelParams *params,
1471         PKIX_PL_X500Name *issuer,
1472         void *plContext);
1473 
1474 /*
1475  * FUNCTION: PKIX_ComCertSelParams_GetSubject
1476  * DESCRIPTION:
1477  *
1478  *  Retrieves a pointer to the X500Name (if any) representing the subject
1479  *  criterion that is set in the ComCertSelParams object pointed to by
1480  *  "params" and stores it at "pSubject". In order to match against this
1481  *  criterion, a certificate's SubjectName must match the criterion's subject
1482  *  name.
1483  *
1484  *  If "params" does not have this criterion set, this function stores NULL at
1485  *  "pSubject", in which case all certificates are considered to match this
1486  *  criterion.
1487  *
1488  * PARAMETERS:
1489  *  "params"
1490  *      Address of ComCertSelParams object whose subject criterion (if any) is
1491  *      to be stored. Must be non-NULL.
1492  *  "pSubject"
1493  *      Address where object pointer will be stored. Must be non-NULL.
1494  *  "plContext"
1495  *      Platform-specific context pointer.
1496  * THREAD SAFETY:
1497  *  Conditionally Thread Safe
1498  *      (see Thread Safety Definitions in Programmer's Guide)
1499  * RETURNS:
1500  *  Returns NULL if the function succeeds.
1501  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1502  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1503  */
1504 PKIX_Error *
1505 PKIX_ComCertSelParams_GetSubject(
1506         PKIX_ComCertSelParams *params,
1507         PKIX_PL_X500Name **pSubject,
1508         void *plContext);
1509 
1510 /*
1511  * FUNCTION: PKIX_ComCertSelParams_SetSubject
1512  * DESCRIPTION:
1513  *
1514  *  Sets the subject criterion of the ComCertSelParams object pointed to by
1515  *  "params" using an X500Name pointed to by "subject". In order to match
1516  *  against this criterion, a certificate's SubjectName must match the
1517  *  criterion's subject name.
1518  *
1519  *  If "subject" is NULL, all certificates are considered to match this
1520  *  criterion.
1521  *
1522  * PARAMETERS:
1523  *  "params"
1524  *      Address of ComCertSelParams object whose subject criterion is to be
1525  *      set. Must be non-NULL.
1526  *  "subject"
1527  *      Address of X500Name used to set the criterion
1528  *      (or NULL to disable the criterion).
1529  *  "plContext"
1530  *      Platform-specific context pointer.
1531  * THREAD SAFETY:
1532  *  Not Thread Safe - assumes exclusive access to "params"
1533  *  (see Thread Safety Definitions in Programmer's Guide)
1534  * RETURNS:
1535  *  Returns NULL if the function succeeds.
1536  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1537  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1538  */
1539 PKIX_Error *
1540 PKIX_ComCertSelParams_SetSubject(
1541         PKIX_ComCertSelParams *params,
1542         PKIX_PL_X500Name *subject,
1543         void *plContext);
1544 
1545 /*
1546  * FUNCTION: PKIX_ComCertSelParams_GetSubjectAsByteArray
1547  * DESCRIPTION:
1548  *
1549  *  Retrieves a pointer to the ByteArray (if any) representing the subject
1550  *  criterion that is set in the ComCertSelParams object pointed to by
1551  *  "params" and stores it at "pSubject". In order to match against this
1552  *  criterion, a certificate's SubjectName must match the criterion's subject
1553  *  name.
1554  *
1555  *  If "params" does not have this criterion set, this function stores NULL at
1556  *  "pSubject", in which case all certificates are considered to match this
1557  *  criterion.
1558  *
1559  * PARAMETERS:
1560  *  "params"
1561  *      Address of ComCertSelParams object whose subject criterion (if any) is
1562  *      to be stored. Must be non-NULL.
1563  *  "pSubject"
1564  *      Address where object pointer will be stored. Must be non-NULL.
1565  *  "plContext"
1566  *      Platform-specific context pointer.
1567  * THREAD SAFETY:
1568  *  Conditionally Thread Safe
1569  *      (see Thread Safety Definitions in Programmer's Guide)
1570  * RETURNS:
1571  *  Returns NULL if the function succeeds.
1572  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1573  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1574  */
1575 PKIX_Error *
1576 PKIX_ComCertSelParams_GetSubjectAsByteArray(
1577         PKIX_ComCertSelParams *params,
1578         PKIX_PL_ByteArray **pSubject,
1579         void *plContext);
1580 
1581 /*
1582  * FUNCTION: PKIX_ComCertSelParams_SetSubjectAsByteArray
1583  * DESCRIPTION:
1584  *
1585  *  Sets the subject criterion of the ComCertSelParams object pointed to by
1586  *  "params" using a ByteArray pointed to by "subject". In order to match
1587  *  against this criterion, a certificate's SubjectName must match the
1588  *  criterion's subject name.
1589  *
1590  *  If "subject" is NULL, all certificates are considered to match this
1591  *  criterion.
1592  *
1593  * PARAMETERS:
1594  *  "params"
1595  *      Address of ComCertSelParams object whose subject criterion is to be
1596  *      set. Must be non-NULL.
1597  *  "subject"
1598  *      Address of ByteArray used to set the criterion
1599  *      (or NULL to disable the criterion).
1600  *  "plContext"
1601  *      Platform-specific context pointer.
1602  * THREAD SAFETY:
1603  *  Not Thread Safe - assumes exclusive access to "params"
1604  *  (see Thread Safety Definitions in Programmer's Guide)
1605  * RETURNS:
1606  *  Returns NULL if the function succeeds.
1607  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1608  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1609  */
1610 PKIX_Error *
1611 PKIX_ComCertSelParams_SetSubjectAsByteArray(
1612         PKIX_ComCertSelParams *params,
1613         PKIX_PL_ByteArray *subject,
1614         void *plContext);
1615 
1616 /*
1617  * FUNCTION: PKIX_ComCertSelParams_GetNameConstraints
1618  * DESCRIPTION:
1619  *
1620  *  Retrieves a pointer to the X500Name (if any) representing the name
1621  *  constraints criterion that is set in the ComCertSelParams object pointed
1622  *  to by "params" and stores it at "pConstraints". In order to match against
1623  *  this criterion, a certificate's subject and subject alternative names must
1624  *  be allowed by the criterion's name constraints.
1625  *
1626  *  If "params" does not have this criterion set, this function stores NULL at
1627  *  "pConstraints", in which case all certificates are considered to match
1628  *  this criterion.
1629  *
1630  * PARAMETERS:
1631  *  "params"
1632  *      Address of ComCertSelParams object whose name constraints criterion
1633  *      (if any) is to be stored. Must be non-NULL.
1634  *  "pConstraints"
1635  *      Address where object pointer will be stored. Must be non-NULL.
1636  *  "plContext"
1637  *      Platform-specific context pointer.
1638  * THREAD SAFETY:
1639  *  Conditionally Thread Safe
1640  *      (see Thread Safety Definitions in Programmer's Guide)
1641  * RETURNS:
1642  *  Returns NULL if the function succeeds.
1643  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1644  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1645  */
1646 PKIX_Error *
1647 PKIX_ComCertSelParams_GetNameConstraints(
1648         PKIX_ComCertSelParams *params,
1649         PKIX_PL_CertNameConstraints **pConstraints,
1650         void *plContext);
1651 
1652 /*
1653  * FUNCTION: PKIX_ComCertSelParams_SetNameConstraints
1654  * DESCRIPTION:
1655  *
1656  *  Sets the name constraints criterion of the ComCertSelParams object pointed
1657  *  to by "params" using the CertNameConstraints pointed to by "constraints".
1658  *  In order to match against this criterion, a certificate's subject and
1659  *  subject alternative names must be allowed by the criterion's name
1660  *  constraints.
1661  *
1662  *  If "constraints" is NULL, all certificates are considered to match this
1663  *  criterion.
1664  *
1665  * PARAMETERS:
1666  *  "params"
1667  *      Address of ComCertSelParams object whose name constraints criterion is
1668  *      to be set. Must be non-NULL.
1669  *  "constraints"
1670  *      Address of CertNameConstraints used to set the criterion
1671  *      (or NULL to disable the criterion).
1672  *  "plContext"
1673  *      Platform-specific context pointer.
1674  * THREAD SAFETY:
1675  *  Not Thread Safe - assumes exclusive access to "params"
1676  *  (see Thread Safety Definitions in Programmer's Guide)
1677  * RETURNS:
1678  *  Returns NULL if the function succeeds.
1679  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1680  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1681  */
1682 PKIX_Error *
1683 PKIX_ComCertSelParams_SetNameConstraints(
1684         PKIX_ComCertSelParams *params,
1685         PKIX_PL_CertNameConstraints *constraints,
1686         void *plContext);
1687 
1688 /*
1689  * FUNCTION: PKIX_ComCertSelParams_GetMatchAllSubjAltNames
1690  * DESCRIPTION:
1691  *
1692  *  Checks whether the ComCertSelParams object pointed to by "params" indicate
1693  *  that all subject alternative names are to be matched and stores the Boolean
1694  *  result at "pMatch". This Boolean value determines the behavior of the
1695  *  subject alternative names criterion.
1696  *
1697  *  In order to match against the subject alternative names criterion, if the
1698  *  Boolean value at "pMatch" is PKIX_TRUE, a certificate must contain all of
1699  *  the criterion's subject alternative names. If the Boolean value at
1700  *  "pMatch" is PKIX_FALSE, a certificate must contain at least one of the
1701  *  criterion's subject alternative names. The default behavior is as if the
1702  *  Boolean value at "pMatch" is PKIX_TRUE.
1703  *
1704  * PARAMETERS:
1705  *  "params"
1706  *      Address of ComCertSelParams object used to determine whether all
1707  *      subject alternative names must be matched. Must be non-NULL.
1708  *  "pMatch"
1709  *      Address where object pointer will be stored. Must be non-NULL.
1710  *  "plContext"
1711  *      Platform-specific context pointer.
1712  * THREAD SAFETY:
1713  *  Conditionally Thread Safe
1714  *      (see Thread Safety Definitions in Programmer's Guide)
1715  * RETURNS:
1716  *  Returns NULL if the function succeeds.
1717  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1718  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1719  */
1720 PKIX_Error *
1721 PKIX_ComCertSelParams_GetMatchAllSubjAltNames(
1722         PKIX_ComCertSelParams *params,
1723         PKIX_Boolean *pMatch,
1724         void *plContext);
1725 
1726 /*
1727  * FUNCTION: PKIX_ComCertSelParams_SetMatchAllSubjAltNames
1728  * DESCRIPTION:
1729  *
1730  *  Sets the match flag of the ComCertSelParams object pointed to by "params"
1731  *  using the Boolean value of "match". This Boolean value determines the
1732  *  behavior of the subject alternative names criterion.
1733  *
1734  *  In order to match against the subject alternative names criterion, if the
1735  *  "match" is PKIX_TRUE, a certificate must contain all of the criterion's
1736  *  subject alternative names. If the "match" is PKIX_FALSE, a certificate
1737  *  must contain at least one of the criterion's subject alternative names.
1738  *  The default behavior is as if "match" is PKIX_TRUE.
1739  *
1740  * PARAMETERS:
1741  *  "params"
1742  *      Address of ComCertSelParams object whose match flag is to be set.
1743  *      Must be non-NULL.
1744  *  "match"
1745  *      Boolean value used to set the match flag.
1746  *  "plContext"
1747  *      Platform-specific context pointer.
1748  * THREAD SAFETY:
1749  *  Not Thread Safe - assumes exclusive access to "params"
1750  *  (see Thread Safety Definitions in Programmer's Guide)
1751  * RETURNS:
1752  *  Returns NULL if the function succeeds.
1753  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1754  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1755  */
1756 PKIX_Error *
1757 PKIX_ComCertSelParams_SetMatchAllSubjAltNames(
1758         PKIX_ComCertSelParams *params,
1759         PKIX_Boolean match,
1760         void *plContext);
1761 
1762 /*
1763  * FUNCTION: PKIX_ComCertSelParams_GetLeafCertFlag
1764  * DESCRIPTION:
1765  *
1766  * Return "leafCert" flag of the ComCertSelParams structure. If set to true,
1767  * the flag indicates that a selector should filter out all cert that are not
1768  * qualified to be a leaf cert according to the specified key/ekey usages.
1769  *
1770  * PARAMETERS:
1771  *  "params"
1772  *      Address of ComCertSelParams object used to determine whether all
1773  *      subject alternative names must be matched. Must be non-NULL.
1774  *  "pLeafFlag"
1775  *      Address of returned value.
1776  *  "plContext"
1777  *      Platform-specific context pointer.
1778  * THREAD SAFETY:
1779  *  Conditionally Thread Safe
1780  *      (see Thread Safety Definitions in Programmer's Guide)
1781  * RETURNS:
1782  *  Returns NULL if the function succeeds.
1783  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1784  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1785  */
1786 PKIX_Error*
1787 PKIX_ComCertSelParams_GetLeafCertFlag(
1788         PKIX_ComCertSelParams *params,
1789         PKIX_Boolean *pLeafFlag,
1790         void *plContext);
1791 
1792 /*
1793  * FUNCTION: PKIX_ComCertSelParams_SetLeafCertFlag
1794  * DESCRIPTION:
1795  *
1796  * Sets a flag that if its value is true, indicates that the selector
1797  * should only pick certs that qualifies to be leaf for this cert path
1798  * validation.
1799  *
1800  * PARAMETERS:
1801  *  "params"
1802  *      Address of ComCertSelParams object whose match flag is to be set.
1803  *      Must be non-NULL.
1804  *  "leafFlag"
1805  *      Boolean value used to set the leaf flag.
1806  *  "plContext"
1807  *      Platform-specific context pointer.
1808  * THREAD SAFETY:
1809  *  Not Thread Safe - assumes exclusive access to "params"
1810  *  (see Thread Safety Definitions in Programmer's Guide)
1811  * RETURNS:
1812  *  Returns NULL if the function succeeds.
1813  *  Returns a CertSelector Error if the function fails in a non-fatal way.
1814  *  Returns a Fatal Error if the function fails in an unrecoverable way.
1815  */
1816 PKIX_Error *
1817 PKIX_ComCertSelParams_SetLeafCertFlag(
1818         PKIX_ComCertSelParams *params,
1819         PKIX_Boolean leafFlag,
1820         void *plContext);
1821 
1822 #ifdef __cplusplus
1823 }
1824 #endif
1825 
1826 #endif /* _PKIX_CERTSEL_H */
1827