The Tor Browser: security/nss/lib/libpkix/include/pkix

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     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  */

    10 #ifndef _PKIX_CERTSEL_H

    11 #define _PKIX_CERTSEL_H

    13 #include "pkixt.h"

    15 #ifdef __cplusplus

    16 extern "C" {

    17 #endif

    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  */

    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  */

    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);

   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);

   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);

   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);

   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);

   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);

   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  */

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

   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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  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);

  1822 #ifdef __cplusplus

  1823 }

  1824 #endif

  1826 #endif /* _PKIX_CERTSEL_H */

The Tor Browser / file revision

security/nss/lib/libpkix/include/pkix_certsel.h@b8a032363ba2

security/nss/lib/libpkix/include/pkix_certsel.h