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