[ tor-browser ].git.dasho

pkix_certsel.h (69090B)
      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 */
	tor-browser The Tor Browser
	git clone https://git.dasho.dev/tor-browser.git
	Log \| Files \| Refs \| README \| LICENSE