mozilla/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  *  "issue"
 160  *      crl issuer.
 161  *  "crlDpList"
 162  *      distribution points list
 163  *  "callback"
 164  *      The MatchCallback function to be used.
 165  *  "pSelector"
 166  *      Address where object pointer will be stored. Must be non-NULL.
 167  *  "plContext"
 168  *      Platform-specific context pointer.
 169  * THREAD SAFETY:
 170  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 171  * RETURNS:
 172  *  Returns NULL if the function succeeds.
 173  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 174  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 175  */
 176 PKIX_Error *
 177 PKIX_CRLSelector_Create(
 178         PKIX_PL_Cert *issuer,
 179         PKIX_List *crlDpList,
 180         PKIX_PL_Date *date,
 181         PKIX_CRLSelector **pSelector,
 182         void *plContext);
 183
 184 /*
 185  * FUNCTION: PKIX_CRLSelector_GetMatchCallback
 186  * DESCRIPTION:
 187  *
 188  *  Retrieves a pointer to "selector's" Match callback function and puts it in
 189  *  "pCallback".
 190  *
 191  * PARAMETERS:
 192  *  "selector"
 193  *      The CRLSelector whose Match callback is desired. Must be non-NULL.
 194  *  "pCallback"
 195  *      Address where Match callback function pointer will be stored.
 196  *      Must be non-NULL.
 197  *  "plContext"
 198  *      Platform-specific context pointer.
 199  * THREAD SAFETY:
 200  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 201  * RETURNS:
 202  *  Returns NULL if the function succeeds.
 203  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 204  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 205  */
 206 PKIX_Error *
 207 PKIX_CRLSelector_GetMatchCallback(
 208         PKIX_CRLSelector *selector,
 209         PKIX_CRLSelector_MatchCallback *pCallback,
 210         void *plContext);
 211
 212 /*
 213  * FUNCTION: PKIX_CRLSelector_GetCRLSelectorContext
 214  * DESCRIPTION:
 215  *
 216  *  Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
 217  *  of the CRLSelector pointed to by "selector" and stores it at
 218  *  "pCRLSelectorContext".
 219  *
 220  * PARAMETERS:
 221  *  "selector"
 222  *      Address of CRLSelector whose context is to be stored. Must be non-NULL.
 223  *  "pCRLSelectorContext"
 224  *      Address where object pointer will be stored. Must be non-NULL.
 225  *  "plContext"
 226  *      Platform-specific context pointer.
 227  * THREAD SAFETY:
 228  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 229  * RETURNS:
 230  *  Returns NULL if the function succeeds.
 231  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 232  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 233  */
 234 PKIX_Error *
 235 PKIX_CRLSelector_GetCRLSelectorContext(
 236         PKIX_CRLSelector *selector,
 237         void **pCRLSelectorContext,
 238         void *plContext);
 239
 240 /*
 241  * FUNCTION: PKIX_CRLSelector_GetCommonCRLSelectorParams
 242  * DESCRIPTION:
 243  *
 244  *  Retrieves a pointer to the ComCRLSelParams object that represent the common
 245  *  parameters of the CRLSelector pointed to by "selector" and stores it at
 246  *  "pCommonCRLSelectorParams". If there are no common parameters stored with
 247  *  the CRLSelector, this function stores NULL at "pCommonCRLSelectorParams".
 248  *
 249  * PARAMETERS:
 250  *  "selector"
 251  *      Address of CRLSelector whose ComCRLSelParams are to be stored.
 252  *      Must be non-NULL.
 253  *  "pCommonCRLSelectorParams"
 254  *      Address where object pointer will be stored. Must be non-NULL.
 255  *  "plContext"
 256  *      Platform-specific context pointer.
 257  * THREAD SAFETY:
 258  *  Conditionally Thread Safe
 259  *      (see Thread Safety Definitions in Programmer's Guide)
 260  * RETURNS:
 261  *  Returns NULL if the function succeeds.
 262  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 263  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 264  */
 265 PKIX_Error *
 266 PKIX_CRLSelector_GetCommonCRLSelectorParams(
 267         PKIX_CRLSelector *selector,
 268         PKIX_ComCRLSelParams **pCommonCRLSelectorParams,
 269         void *plContext);
 270
 271 /*
 272  * FUNCTION: PKIX_CRLSelector_SetCommonCRLSelectorParams
 273  * DESCRIPTION:
 274  *
 275  *  Sets the common parameters for the CRLSelector pointed to by "selector"
 276  *  using the ComCRLSelParams pointed to by "commonCRLSelectorParams".
 277  *
 278  * PARAMETERS:
 279  *  "selector"
 280  *      Address of CRLSelector whose common parameters are to be set.
 281  *      Must be non-NULL.
 282  *  "commonCRLSelectorParams"
 283  *      Address of ComCRLSelParams representing the common parameters.
 284  *  "plContext"
 285  *      Platform-specific context pointer.
 286  * THREAD SAFETY:
 287  *  Not Thread Safe - assumes exclusive access to "selector"
 288  *  (see Thread Safety Definitions in Programmer's Guide)
 289  * RETURNS:
 290  *  Returns NULL if the function succeeds.
 291  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 292  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 293  */
 294 PKIX_Error *
 295 PKIX_CRLSelector_SetCommonCRLSelectorParams(
 296         PKIX_CRLSelector *selector,
 297         PKIX_ComCRLSelParams *commonCRLSelectorParams,
 298         void *plContext);
 299
 300 /* PKIX_ComCRLSelParams
 301  *
 302  * PKIX_ComCRLSelParams are X.509 parameters commonly used with CRLSelectors,
 303  * especially determining which CRLs to retrieve from a CertStore.
 304  * PKIX_ComCRLSelParams are typically used with those CRLSelectors that use
 305  * the default implementation of MatchCallback, which understands how to
 306  * process ComCRLSelParams.
 307  */
 308
 309 /*
 310  * FUNCTION: PKIX_ComCRLSelParams_Create
 311  * DESCRIPTION:
 312  *
 313  *  Creates a new ComCRLSelParams object and stores it at "pParams".
 314  *
 315  * PARAMETERS:
 316  *  "pParams"
 317  *      Address where object pointer will be stored. Must be non-NULL.
 318  *  "plContext"
 319  *      Platform-specific context pointer.
 320  * THREAD SAFETY:
 321  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 322  * RETURNS:
 323  *  Returns NULL if the function succeeds.
 324  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 325  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 326  */
 327 PKIX_Error *
 328 PKIX_ComCRLSelParams_Create(
 329         PKIX_ComCRLSelParams **pParams,
 330         void *plContext);
 331
 332 /*
 333  * FUNCTION: PKIX_ComCRLSelParams_GetIssuerNames
 334  * DESCRIPTION:
 335  *
 336  *  Retrieves a pointer to the List of X500Names (if any) representing the
 337  *  issuer names criterion that is set in the ComCRLSelParams pointed to by
 338  *  "params" and stores it at "pNames". In order to match against this
 339  *  criterion, a CRL's IssuerName must match at least one of the criterion's
 340  *  issuer names.
 341  *
 342  *  If "params" does not have this criterion set, this function stores NULL at
 343  *  "pNames", in which case all CRLs are considered to match.
 344  *
 345  *  Note that the List returned by this function is immutable.
 346  *
 347  * PARAMETERS:
 348  *  "params"
 349  *      Address of ComCRLSelParams whose issuer names criterion (if any) is to
 350  *      be stored. Must be non-NULL.
 351  *  "pNames"
 352  *      Address where object pointer will be stored. Must be non-NULL.
 353  *  "plContext"
 354  *      Platform-specific context pointer.
 355  * THREAD SAFETY:
 356  *  Conditionally Thread Safe
 357  *      (see Thread Safety Definitions in Programmer's Guide)
 358  * RETURNS:
 359  *  Returns NULL if the function succeeds.
 360  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 361  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 362  */
 363 PKIX_Error *
 364 PKIX_ComCRLSelParams_GetIssuerNames(
 365         PKIX_ComCRLSelParams *params,
 366         PKIX_List **pNames,  /* list of PKIX_PL_X500Name */
 367         void *plContext);
 368
 369 /*
 370  * FUNCTION: PKIX_ComCRLSelParams_SetIssuerNames
 371  * DESCRIPTION:
 372  *
 373  *  Sets the issuer names criterion of the ComCRLSelParams pointed to by
 374  *  "params" using a List of X500Names pointed to by "names". In order to match
 375  *  against this criterion, a CRL's IssuerName must match at least one of the
 376  *  criterion's issuer names.
 377  *
 378  * PARAMETERS:
 379  *  "params"
 380  *      Address of ComCRLSelParamsParams whose issuer names criterion is to be
 381  *      set. Must be non-NULL.
 382  *  "names"
 383  *      Address of List of X500Names used to set the criterion
 384  *  "plContext"
 385  *      Platform-specific context pointer.
 386  * THREAD SAFETY:
 387  *  Not Thread Safe - assumes exclusive access to "params"
 388  *  (see Thread Safety Definitions in Programmer's Guide)
 389  * RETURNS:
 390  *  Returns NULL if the function succeeds.
 391  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 392  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 393  */
 394 PKIX_Error *
 395 PKIX_ComCRLSelParams_SetIssuerNames(
 396         PKIX_ComCRLSelParams *params,
 397         PKIX_List *names,   /* list of PKIX_PL_X500Name */
 398         void *plContext);
 399
 400 /*
 401  * FUNCTION: PKIX_ComCRLSelParams_AddIssuerName
 402  * DESCRIPTION:
 403  *
 404  *  Adds to the issuer names criterion of the ComCRLSelParams pointed to by
 405  *  "params" using the X500Name pointed to by "name". In order to match
 406  *  against this criterion, a CRL's IssuerName must match at least one of the
 407  *  criterion's issuer names.
 408  *
 409  * PARAMETERS:
 410  *  "params"
 411  *      Address of ComCRLSelParams whose issuer names criterion is to be added
 412  *      to. Must be non-NULL.
 413  *  "name"
 414  *      Address of X500Name to be added.
 415  *  "plContext"
 416  *      Platform-specific context pointer.
 417  * THREAD SAFETY:
 418  *  Not Thread Safe - assumes exclusive access to "params"
 419  *  (see Thread Safety Definitions in Programmer's Guide)
 420  * RETURNS:
 421  *  Returns NULL if the function succeeds.
 422  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 423  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 424  */
 425 PKIX_Error *
 426 PKIX_ComCRLSelParams_AddIssuerName(
 427         PKIX_ComCRLSelParams *params,
 428         PKIX_PL_X500Name *name,
 429         void *plContext);
 430
 431 /*
 432  * FUNCTION: PKIX_ComCRLSelParams_GetCertificateChecking
 433  * DESCRIPTION:
 434  *
 435  *  Retrieves a pointer to the Cert (if any) representing the certificate whose
 436  *  revocation status is being checked. This is not a criterion. It is simply
 437  *  optional information that may help a CertStore find relevant CRLs.
 438  *
 439  *  If "params" does not have a certificate set, this function stores NULL at
 440  *  "pCert", in which case there is no optional information to provide.
 441  *
 442  * PARAMETERS:
 443  *  "params"
 444  *      Address of ComCRLSelParams whose certificate being checked (if any) is
 445  *      to be stored. Must be non-NULL.
 446  *  "pCert"
 447  *      Address where object pointer will be stored. Must be non-NULL.
 448  *  "plContext"
 449  *      Platform-specific context pointer.
 450  * THREAD SAFETY:
 451  *  Conditionally Thread Safe
 452  *      (see Thread Safety Definitions in Programmer's Guide)
 453  * RETURNS:
 454  *  Returns NULL if the function succeeds
 455  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 456  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 457  */
 458 PKIX_Error *
 459 PKIX_ComCRLSelParams_GetCertificateChecking(
 460         PKIX_ComCRLSelParams *params,
 461         PKIX_PL_Cert **pCert,
 462         void *plContext);
 463
 464 /*
 465  * FUNCTION: PKIX_ComCRLSelParams_SetCertificateChecking
 466  * DESCRIPTION:
 467  *
 468  *  Sets the ComCRLSelParams pointed to by "params" with the certificate
 469  *  (pointed to by "cert") whose revocation status is being checked. This is
 470  *  not a criterion. It is simply optional information that may help a
 471  *  CertStore find relevant CRLs.
 472  *
 473  * PARAMETERS:
 474  *  "params"
 475  *      Address of ComCRLSelParams whose certificate being checked is to be
 476  *      set. Must be non-NULL.
 477  *  "cert"
 478  *      Address of Cert whose revocation status is being checked
 479  *  "plContext"
 480  *      Platform-specific context pointer.
 481  * THREAD SAFETY:
 482  *  Not Thread Safe - assumes exclusive access to "params"
 483  *  (see Thread Safety Definitions in Programmer's Guide)
 484  * RETURNS:
 485  *  Returns NULL if the function succeeds.
 486  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 487  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 488  */
 489 PKIX_Error *
 490 PKIX_ComCRLSelParams_SetCertificateChecking(
 491         PKIX_ComCRLSelParams *params,
 492         PKIX_PL_Cert *cert,
 493         void *plContext);
 494
 495 /*
 496  * FUNCTION: PKIX_ComCRLSelParams_GetDateAndTime
 497  * DESCRIPTION:
 498  *
 499  *  Retrieves a pointer to the Date (if any) representing the dateAndTime
 500  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
 501  *  stores it at "pDate". In order to match against this criterion, a CRL's
 502  *  thisUpdate component must be less than or equal to the criterion's
 503  *  dateAndTime and the CRL's nextUpdate component must be later than the
 504  *  criterion's dateAndTime. There is no match if the CRL does not contain a
 505  *  nextUpdate component.
 506  *
 507  *  If "params" does not have this criterion set, this function stores NULL at
 508  *  "pDate", in which case all CRLs are considered to match.
 509  *
 510  * PARAMETERS:
 511  *  "params"
 512  *      Address of ComCRLSelParams whose dateAndTime criterion (if any) is to
 513  *      be stored. Must be non-NULL.
 514  *  "pDate"
 515  *      Address where object pointer will be stored. Must be non-NULL.
 516  *  "plContext"
 517  *      Platform-specific context pointer.
 518  * THREAD SAFETY:
 519  *  Conditionally Thread Safe
 520  *      (see Thread Safety Definitions in Programmer's Guide)
 521  * RETURNS:
 522  *  Returns NULL if the function succeeds.
 523  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 524  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 525  */
 526 PKIX_Error *
 527 PKIX_ComCRLSelParams_GetDateAndTime(
 528         PKIX_ComCRLSelParams *params,
 529         PKIX_PL_Date **pDate,
 530         void *plContext);
 531
 532 /*
 533  * FUNCTION: PKIX_ComCRLSelParams_SetDateAndTime
 534  * DESCRIPTION:
 535  *
 536  *  Sets the dateAndTime criterion of the ComCRLSelParams pointed to by
 537  *  "params" using a Date pointed to by "date". In order to match against this
 538  *  criterion, a CRL's thisUpdate component must be less than or equal to the
 539  *  criterion's dateAndTime and the CRL's nextUpdate component must be later
 540  *  than the criterion's dateAndTime. There is no match if the CRL does not
 541  *  contain a nextUpdate component.
 542  *
 543  * PARAMETERS:
 544  *  "params"
 545  *      Address of ComCRLSelParamsParams whose dateAndTime criterion is to be
 546  *      set. Must be non-NULL.
 547  *  "date"
 548  *      Address of Date used to set the criterion
 549  *  "plContext"
 550  *      Platform-specific context pointer.
 551  * THREAD SAFETY:
 552  *  Not Thread Safe - assumes exclusive access to "params"
 553  *  (see Thread Safety Definitions in Programmer's Guide)
 554  * RETURNS:
 555  *  Returns NULL if the function succeeds.
 556  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 557  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 558  */
 559 PKIX_Error *
 560 PKIX_ComCRLSelParams_SetDateAndTime(
 561         PKIX_ComCRLSelParams *params,
 562         PKIX_PL_Date *date,
 563         void *plContext);
 564
 565 /*
 566  * FUNCTION: PKIX_ComCRLSelParams_GetNISTPolicyEnabled
 567  * DESCRIPTION:
 568  *
 569  *  Retrieves a pointer to the Boolean representing the NIST CRL policy
 570  *  activation flag that is set in the ComCRLSelParams pointed to by "params"
 571  *  and stores it at "enabled". If enabled, a CRL must have nextUpdate field.
 572  *
 573  *  Default value for this flag is TRUE.
 574  *
 575  * PARAMETERS:
 576  *  "params"
 577  *      Address of ComCRLSelParams whose NIST CRL policy criterion  is to
 578  *      be stored. Must be non-NULL.
 579  *  "pEnabled"
 580  *      Address where object pointer will be stored. Must be non-NULL.
 581  *  "plContext"
 582  *      Platform-specific context pointer.
 583  * THREAD SAFETY:
 584  *  Conditionally Thread Safe
 585  *      (see Thread Safety Definitions in Programmer's Guide)
 586  * RETURNS:
 587  *  Returns NULL if the function succeeds.
 588  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 589  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 590  */
 591 PKIX_Error *
 592 PKIX_ComCRLSelParams_GetNISTPolicyEnabled(
 593         PKIX_ComCRLSelParams *params,
 594         PKIX_Boolean *pEnabled,
 595         void *plContext);
 596
 597 /*
 598  * FUNCTION: PKIX_ComCRLSelParams_SetNISTPolicyEnabled
 599  * DESCRIPTION:
 600  *
 601  *  Sets the NIST crl policy criterion of the ComCRLSelParams pointed to by
 602  *  "params" using a "enabled" flag. In order to match against this
 603  *  criterion, a CRL's nextUpdate must be available and criterion's
 604  *  dataAndTime must be within thisUpdate and nextUpdate time period.
 605  *
 606  * PARAMETERS:
 607  *  "params"
 608  *      Address of ComCRLSelParamsParams whose NIST CRL policy criterion
 609  *      is to be set. Must be non-NULL.
 610  *  "enabled"
 611  *      Address of Bollean 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 CRLSelector 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_ComCRLSelParams_SetNISTPolicyEnabled(
 624         PKIX_ComCRLSelParams *params,
 625         PKIX_Boolean enabled,
 626         void *plContext);
 627
 628 /*
 629  * FUNCTION: PKIX_ComCRLSelParams_GetMaxCRLNumber
 630  * DESCRIPTION:
 631  *
 632  *  Retrieves a pointer to the BigInt (if any) representing the maxCRLNumber
 633  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
 634  *  stores it at "pNumber". In order to match against this criterion, a CRL
 635  *  must have a CRL number extension whose value is less than or equal to the
 636  *  criterion's value.
 637  *
 638  *  If "params" does not have this criterion set, this function stores NULL at
 639  *  "pNumber", in which case all CRLs are considered to match.
 640  *
 641  * PARAMETERS:
 642  *  "params"
 643  *      Address of ComCRLSelParams whose maxCRLNumber criterion (if any) is to
 644  *      be stored. Must be non-NULL.
 645  *  "pNumber"
 646  *      Address where object pointer will be stored. Must be non-NULL.
 647  *  "plContext"
 648  *      Platform-specific context pointer.
 649  * THREAD SAFETY:
 650  *  Conditionally Thread Safe
 651  *      (see Thread Safety Definitions in Programmer's Guide)
 652  * RETURNS:
 653  *  Returns NULL if the function succeeds.
 654  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 655  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 656  */
 657 PKIX_Error *
 658 PKIX_ComCRLSelParams_GetMaxCRLNumber(
 659         PKIX_ComCRLSelParams *params,
 660         PKIX_PL_BigInt **pNumber,
 661         void *plContext);
 662
 663 /*
 664  * FUNCTION: PKIX_ComCRLSelParams_SetMaxCRLNumber
 665  * DESCRIPTION:
 666  *
 667  *  Sets the maxCRLNumber criterion of the ComCRLSelParams pointed to by
 668  *  "params" using a BigInt pointed to by "number". In order to match against
 669  *  this criterion, a CRL must have a CRL number extension whose value is less
 670  *  than or equal to the criterion's value.
 671  *
 672  * PARAMETERS:
 673  *  "params"
 674  *      Address of ComCRLSelParamsParams whose maxCRLNumber criterion is to be
 675  *      set. Must be non-NULL.
 676  *  "number"
 677  *      Address of BigInt used to set the criterion
 678  *  "plContext"
 679  *      Platform-specific context pointer.
 680  * THREAD SAFETY:
 681  *  Not Thread Safe - assumes exclusive access to "params"
 682  *  (see Thread Safety Definitions in Programmer's Guide)
 683  * RETURNS:
 684  *  Returns NULL if the function succeeds.
 685  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 686  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 687  */
 688 PKIX_Error *
 689 PKIX_ComCRLSelParams_SetMaxCRLNumber(
 690         PKIX_ComCRLSelParams *params,
 691         PKIX_PL_BigInt *number,
 692         void *plContext);
 693
 694 /*
 695  * FUNCTION: PKIX_ComCRLSelParams_GetMinCRLNumber
 696  * DESCRIPTION:
 697  *
 698  *  Retrieves a pointer to the BigInt (if any) representing the minCRLNumber
 699  *  criterion that is set in the ComCRLSelParams pointed to by "params" and
 700  *  stores it at "pNumber". In order to match against this criterion, a CRL
 701  *  must have a CRL number extension whose value is greater than or equal to
 702  *  the criterion's value.
 703  *
 704  *  If "params" does not have this criterion set, this function stores NULL at
 705  *  "pNumber", in which case all CRLs are considered to match.
 706  *
 707  * PARAMETERS:
 708  *  "params"
 709  *      Address of ComCRLSelParams whose minCRLNumber criterion (if any) is to
 710  *      be stored. Must be non-NULL.
 711  *  "pNumber"
 712  *      Address where object pointer will be stored. Must be non-NULL.
 713  *  "plContext"
 714  *      Platform-specific context pointer.
 715  * THREAD SAFETY:
 716  *  Conditionally Thread Safe
 717  *      (see Thread Safety Definitions in Programmer's Guide)
 718  * RETURNS:
 719  *  Returns NULL if the function succeeds.
 720  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 721  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 722  */
 723 PKIX_Error *
 724 PKIX_ComCRLSelParams_GetMinCRLNumber(
 725         PKIX_ComCRLSelParams *params,
 726         PKIX_PL_BigInt **pNumber,
 727         void *plContext);
 728
 729 /*
 730  * FUNCTION: PKIX_ComCRLSelParams_SetMinCRLNumber
 731  * DESCRIPTION:
 732  *
 733  *  Sets the minCRLNumber criterion of the ComCRLSelParams pointed to by
 734  *  "params" using a BigInt pointed to by "number". In order to match against
 735  *  this criterion, a CRL must have a CRL number extension whose value is
 736  *  greater than or equal to the criterion's value.
 737  *
 738  * PARAMETERS:
 739  *  "params"
 740  *      Address of ComCRLSelParamsParams whose minCRLNumber criterion is to be
 741  *      set. Must be non-NULL.
 742  *  "number"
 743  *      Address of BigInt used to set the criterion
 744  *  "plContext"
 745  *      Platform-specific context pointer.
 746  * THREAD SAFETY:
 747  *  Not Thread Safe - assumes exclusive access to "params"
 748  *  (see Thread Safety Definitions in Programmer's Guide)
 749  * RETURNS:
 750  *  Returns NULL if the function succeeds.
 751  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 752  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 753  */
 754 PKIX_Error *
 755 PKIX_ComCRLSelParams_SetMinCRLNumber(
 756         PKIX_ComCRLSelParams *params,
 757         PKIX_PL_BigInt *number,
 758         void *plContext);
 759
 760 /*
 761  * FUNCTION: PKIX_ComCRLSelParams_SetCrlDp
 762  * DESCRIPTION:
 763  *
 764  * Sets crldp list that can be used to download a crls.
 765  *
 766  * PARAMETERS:
 767  *  "params"
 768  *      Address of ComCRLSelParamsParams whose minCRLNumber criterion is to be
 769  *      set. Must be non-NULL.
 770  *  "crldpList"
 771  *      A list of CRLDPs. Can be an emptry list.
 772  *  "plContext"
 773  *      Platform-specific context pointer.
 774  * THREAD SAFETY:
 775  *  Not Thread Safe - assumes exclusive access to "params"
 776  *  (see Thread Safety Definitions in Programmer's Guide)
 777  * RETURNS:
 778  *  Returns NULL if the function succeeds.
 779  *  Returns a CRLSelector Error if the function fails in a non-fatal way.
 780  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 781  */
 782 PKIX_Error*
 783 PKIX_ComCRLSelParams_SetCrlDp(
 784          PKIX_ComCRLSelParams *params,
 785          PKIX_List *crldpList,
 786          void *plContext);
 787
 788 #ifdef __cplusplus
 789 }
 790 #endif
 791
 792 #endif /* _PKIX_CRLSEL_H */