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

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