security/nss/lib/libpkix/include/pkix_checker.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_CertChainChecker type.
  39  *
  40  */
  41
  42 #ifndef _PKIX_CHECKER_H
  43 #define _PKIX_CHECKER_H
  44
  45 #include "pkixt.h"
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /* General
  52  *
  53  * Please refer to the libpkix Programmer's Guide for detailed information
  54  * about how to use the libpkix library. Certain key warnings and notices from
  55  * that document are repeated here for emphasis.
  56  *
  57  * All identifiers in this file (and all public identifiers defined in
  58  * libpkix) begin with "PKIX_". Private identifiers only intended for use
  59  * within the library begin with "pkix_".
  60  *
  61  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
  62  *
  63  * Unless otherwise noted, for all accessor (gettor) functions that return a
  64  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
  65  * shared object. Therefore, the caller should treat this shared object as
  66  * read-only and should not modify this shared object. When done using the
  67  * shared object, the caller should release the reference to the object by
  68  * using the PKIX_PL_Object_DecRef function.
  69  *
  70  * While a function is executing, if its arguments (or anything referred to by
  71  * its arguments) are modified, free'd, or destroyed, the function's behavior
  72  * is undefined.
  73  *
  74  */
  75
  76 /* PKIX_CertChainChecker
  77  *
  78  * PKIX_CertChainCheckers provide a standard way for the caller to insert their
  79  * own custom checks to validate certificates. This may be useful in many
  80  * scenarios, including when the caller wishes to validate private certificate
  81  * extensions. The CheckCallback allows custom certificate processing to take
  82  * place. Additionally, a CertChainChecker can optionally maintain state
  83  * between successive calls to the CheckCallback. This certChainCheckerState
  84  * must be an Object (although any object type), allowing it to be
  85  * reference-counted and allowing it to provide the standard Object functions
  86  * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes
  87  * their CertChainChecker to be used during chain building, their
  88  * certChainCheckerState object must implement an appropriate Duplicate
  89  * function. The builder uses this Duplicate function when backtracking.
  90  *
  91  * Once the caller has created a CertChainChecker object, the caller then
  92  * specifies a CertChainChecker object in a ProcessingParams object
  93  * and passes the ProcessingParams object to PKIX_ValidateChain or
  94  * PKIX_BuildChain, which uses the objects to call the user's callback
  95  * functions as needed during the validation or building process.
  96  *
  97  * A CertChainChecker may be presented certificates in the "reverse" direction
  98  * (from trust anchor to target) or in the "forward" direction (from target to
  99  * trust anchor). All CertChainCheckers must support "reverse checking", while
 100  * support for "forward checking" is optional, but recommended. If "forward
 101  * checking" is not supported, building chains may be much less efficient. The
 102  * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to
 103  * determine whether forward checking is supported, and the
 104  * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to
 105  * determine whether the CertChainChecker has been initialized to expect the
 106  * certificates to be presented in the "forward" direction.
 107  */
 108
 109 /*
 110  * FUNCTION: PKIX_CertChainChecker_CheckCallback
 111  * DESCRIPTION:
 112  *
 113  *  This callback function checks whether the specified Cert pointed to by
 114  *  "cert" is valid using "checker's" internal certChainCheckerState (if any)
 115  *  and removes the critical extensions that it processes (if any) from the
 116  *  List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions".
 117  *  If the checker finds that the certificate is not valid, an Error pointer is
 118  *  returned.
 119  *
 120  *  If the checker uses non-blocking I/O, the address of a platform-dependent
 121  *  non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext",
 122  *  which the caller may use, in a platform-dependent way, to wait, poll, or
 123  *  otherwise determine when to try again. If the checker does not use
 124  *  non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL
 125  *  value was stored, on a subsequent call the checker will attempt to complete
 126  *  the pending I/O and, if successful, NULL will be stored at "pNBIOContext".
 127  *
 128  * PARAMETERS:
 129  *  "checker"
 130  *      Address of CertChainChecker whose certChainCheckerState and
 131  *      CheckCallback logic is to be used. Must be non-NULL.
 132  *  "cert"
 133  *      Address of Cert that is to be validated using "checker".
 134  *      Must be non-NULL.
 135  *  "unresolvedCriticalExtensions"
 136  *      Address of List of OIDs that represents the critical certificate
 137  *      extensions that have yet to be resolved. This parameter may be
 138  *      modified during the function call. Must be non-NULL.
 139  *  "pNBIOContext"
 140  *      Address at which is stored a platform-dependent structure indicating
 141  *      whether checking was suspended for non-blocking I/O. Must be non-NULL.
 142  *  "plContext"
 143  *      Platform-specific context pointer.
 144  * THREAD SAFETY:
 145  *  Thread Safe
 146  *
 147  *  Multiple threads must be able to safely call this function without
 148  *  worrying about conflicts, even if they're operating on the same object.
 149  * RETURNS:
 150  *  Returns NULL if the function succeeds.
 151  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 152  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 153  */
 154 typedef PKIX_Error *
 155 (*PKIX_CertChainChecker_CheckCallback)(
 156         PKIX_CertChainChecker *checker,
 157         PKIX_PL_Cert *cert,
 158         PKIX_List *unresolvedCriticalExtensions,  /* list of PKIX_PL_OID */
 159         void **pNBIOContext,
 160         void *plContext);
 161
 162 /*
 163  * FUNCTION: PKIX_CertChainChecker_Create
 164  * DESCRIPTION:
 165  *
 166  *  Creates a new CertChainChecker and stores it at "pChecker". The new
 167  *  CertChainChecker uses the CheckCallback pointed to by "callback" as its
 168  *  callback function. It uses the Object pointed to by "initialState" (if
 169  *  any) as its initial state. As noted above, the initial state Object must
 170  *  provide a custom implementation of PKIX_PL_Object_Duplicate if the
 171  *  CertChainChecker is to be used during certificate chain building.
 172  *
 173  *  A CertChainChecker may be presented certificates in the "reverse"
 174  *  direction (from trust anchor to target) or in the "forward" direction
 175  *  (from target to trust anchor). All CertChainCheckers must support
 176  *  "reverse checking", while support for "forward checking" is optional. The
 177  *  CertChainChecker is initialized with two Boolean flags that deal with this
 178  *  distinction: "forwardCheckingSupported" and "forwardDirectionExpected".
 179  *  If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that
 180  *  this CertChainChecker is capable of checking certificates in the "forward"
 181  *  direction (as well as the "reverse" direction, which all CertChainCheckers
 182  *  MUST support). The "forwardDirectionExpected" Boolean flag indicates in
 183  *  which direction the CertChainChecker should expect the certificates to be
 184  *  presented. This is particularly useful for CertChainCheckers that are
 185  *  capable of checking in either the "forward" direction or the "reverse"
 186  *  direction, but have different processing steps depending on the direction.
 187  *
 188  *  The CertChainChecker also uses the List of OIDs pointed to by "extensions"
 189  *  as the supported certificate extensions. All certificate extensions that
 190  *  the CertChainChecker might possibly recognize and be able to process
 191  *  should be included in the List of supported extensions. If "checker" does
 192  *  not recognize or process any certificate extensions, "extensions" should
 193  *  be set to NULL.
 194  *
 195  * PARAMETERS:
 196  *  "callback"
 197  *      The CheckCallback function to be used. Must be non-NULL.
 198  *  "forwardCheckingSupported"
 199  *      A Boolean value indicating whether or not this CertChainChecker is
 200  *      capable of checking certificates in the "forward" direction.
 201  *  "forwardDirectionExpected"
 202  *      A Boolean value indicating whether or not this CertChainChecker should
 203  *      be used to check in the "forward" direction.
 204  *  "extensions"
 205  *      Address of List of OIDs representing the supported extensions.
 206  *  "initialState"
 207  *      Address of Object representing the CertChainChecker's initial state
 208  *      (if any).
 209  *  "pChecker"
 210  *      Address where object pointer will be stored. Must be non-NULL.
 211  *  "plContext"
 212  *      Platform-specific context pointer.
 213  * THREAD SAFETY:
 214  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 215  * RETURNS:
 216  *  Returns NULL if the function succeeds.
 217  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 218  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 219  */
 220 PKIX_Error *
 221 PKIX_CertChainChecker_Create(
 222     PKIX_CertChainChecker_CheckCallback callback,
 223     PKIX_Boolean forwardCheckingSupported,
 224     PKIX_Boolean forwardDirectionExpected,
 225     PKIX_List *extensions,  /* list of PKIX_PL_OID */
 226     PKIX_PL_Object *initialState,
 227     PKIX_CertChainChecker **pChecker,
 228     void *plContext);
 229
 230 /*
 231  * FUNCTION: PKIX_CertChainChecker_GetCheckCallback
 232  * DESCRIPTION:
 233  *
 234  *  Retrieves a pointer to "checker's" Check callback function and puts it in
 235  *  "pCallback".
 236  *
 237  * PARAMETERS:
 238  *  "checker"
 239  *      The CertChainChecker whose Check callback is desired. Must be non-NULL.
 240  *  "pCallback"
 241  *      Address where Check callback function pointer will be stored.
 242  *      Must be non-NULL.
 243  *  "plContext"
 244  *      Platform-specific context pointer.
 245  * THREAD SAFETY:
 246  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 247  * RETURNS:
 248  *  Returns NULL if the function succeeds.
 249  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 250  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 251  */
 252 PKIX_Error *
 253 PKIX_CertChainChecker_GetCheckCallback(
 254         PKIX_CertChainChecker *checker,
 255         PKIX_CertChainChecker_CheckCallback *pCallback,
 256         void *plContext);
 257
 258 /*
 259  * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported
 260  * DESCRIPTION:
 261  *
 262  *  Checks whether forward checking is supported by the CertChainChecker
 263  *  pointed to by "checker" and stores the Boolean result at
 264  *  "pForwardCheckingSupported".
 265  *
 266  *  A CertChainChecker may be presented certificates in the "reverse"
 267  *  direction (from trust anchor to target) or in the "forward" direction
 268  *  (from target to trust anchor). All CertChainCheckers must support
 269  *  "reverse checking", while support for "forward checking" is optional. This
 270  *  function is used to determine whether forward checking is supported.
 271  *
 272  * PARAMETERS:
 273  *  "checker"
 274  *      The CertChainChecker whose ability to validate certificates in the
 275  *      "forward" direction is to be checked. Must be non-NULL.
 276  *  "pForwardCheckingSupported"
 277  *      Destination of the Boolean result. Must be non-NULL.
 278  *  "plContext"
 279  *      Platform-specific context pointer.
 280  * THREAD SAFETY:
 281  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 282  * RETURNS:
 283  *  Returns NULL if the function succeeds.
 284  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 285  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 286  */
 287 PKIX_Error *
 288 PKIX_CertChainChecker_IsForwardCheckingSupported(
 289         PKIX_CertChainChecker *checker,
 290         PKIX_Boolean *pForwardCheckingSupported,
 291         void *plContext);
 292
 293 /*
 294  * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected
 295  * DESCRIPTION:
 296  *
 297  *  Checks whether the CertChainChecker pointed to by "checker" has been
 298  *  initialized to expect the certificates to be presented in the "forward"
 299  *  direction and stores the Boolean result at "pForwardDirectionExpected".
 300  *
 301  *  A CertChainChecker may be presented certificates in the "reverse"
 302  *  direction (from trust anchor to target) or in the "forward" direction
 303  *  (from target to trust anchor). All CertChainCheckers must support
 304  *  "reverse checking", while support for "forward checking" is optional. This
 305  *  function is used to determine in which direction the CertChainChecker
 306  *  expects the certificates to be presented.
 307  *
 308  * PARAMETERS:
 309  *  "checker"
 310  *      The CertChainChecker that has been initialized to expect certificates
 311  *      in either the "forward" or "reverse" directions. Must be non-NULL.
 312  *  "pForwardDirectionExpected"
 313  *      Destination of the Boolean result. Must be non-NULL.
 314  *  "plContext"
 315  *      Platform-specific context pointer.
 316  * THREAD SAFETY:
 317  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 318  * RETURNS:
 319  *  Returns NULL if the function succeeds.
 320  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 321  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 322  */
 323 PKIX_Error *
 324 PKIX_CertChainChecker_IsForwardDirectionExpected(
 325         PKIX_CertChainChecker *checker,
 326         PKIX_Boolean *pForwardDirectionExpected,
 327         void *plContext);
 328
 329 /*
 330  * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions
 331  * DESCRIPTION:
 332  *
 333  *  Retrieves a pointer to a List of OIDs (each OID corresponding to a
 334  *  certificate extension supported by the CertChainChecker pointed to by
 335  *  "checker") and stores it at "pExtensions". All certificate extensions that
 336  *  the CertChainChecker might possibly recognize and be able to process
 337  *  should be included in the List of supported extensions. If "checker" does
 338  *  not recognize or process any certificate extensions, this function stores
 339  *  NULL at "pExtensions".
 340  *
 341  *  Note that the List returned by this function is immutable.
 342  *
 343  * PARAMETERS:
 344  *  "checker"
 345  *      Address of CertChainChecker whose supported extension OIDs are to be
 346  *      stored. Must be non-NULL.
 347  *  "pExtensions"
 348  *      Address where object pointer will be stored. Must be non-NULL.
 349  *  "plContext"
 350  *      Platform-specific context pointer.
 351  * THREAD SAFETY:
 352  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 353  * RETURNS:
 354  *  Returns NULL if the function succeeds.
 355  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 356  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 357  */
 358 PKIX_Error *
 359 PKIX_CertChainChecker_GetSupportedExtensions(
 360         PKIX_CertChainChecker *checker,
 361         PKIX_List **pExtensions, /* list of PKIX_PL_OID */
 362         void *plContext);
 363
 364 /*
 365  * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState
 366  * DESCRIPTION:
 367  *
 368  *  Retrieves a pointer to a PKIX_PL_Object representing the internal state
 369  *  (if any) of the CertChainChecker pointed to by "checker" and stores it at
 370  *  "pCertChainCheckerState".
 371  *
 372  * PARAMETERS:
 373  *  "checker"
 374  *      Address of CertChainChecker whose state is to be stored.
 375  *      Must be non-NULL.
 376  *  "pCertChainCheckerState"
 377  *      Address where object pointer will be stored. Must be non-NULL.
 378  *  "plContext"
 379  *      Platform-specific context pointer.
 380  * THREAD SAFETY:
 381  *  Conditionally Thread Safe
 382  *      (see Thread Safety Definitions in Programmer's Guide)
 383  * RETURNS:
 384  *  Returns NULL if the function succeeds.
 385  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 386  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 387  */
 388 PKIX_Error *
 389 PKIX_CertChainChecker_GetCertChainCheckerState(
 390         PKIX_CertChainChecker *checker,
 391         PKIX_PL_Object **pCertChainCheckerState,
 392         void *plContext);
 393
 394 /*
 395  * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState
 396  * DESCRIPTION:
 397  *
 398  *  Sets the internal state of the CertChainChecker pointed to by "checker"
 399  *  using the Object pointed to by "certChainCheckerState". If "checker" needs
 400  *  a NULL internal state, "certChainCheckerState" should be set to NULL.
 401  *
 402  * PARAMETERS:
 403  *  "checker"
 404  *      Address of CertChainChecker whose state is to be set. Must be non-NULL.
 405  *  "certChainCheckerState"
 406  *      Address of Object representing internal state.
 407  *  "plContext"
 408  *      Platform-specific context pointer.
 409  * THREAD SAFETY:
 410  *  Not Thread Safe - assumes exclusive access to "checker"
 411  *  (see Thread Safety Definitions in Programmer's Guide)
 412  * RETURNS:
 413  *  Returns NULL if the function succeeds.
 414  *  Returns a CertChainChecker Error if the function fails in a non-fatal way.
 415  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 416  */
 417 PKIX_Error *
 418 PKIX_CertChainChecker_SetCertChainCheckerState(
 419         PKIX_CertChainChecker *checker,
 420         PKIX_PL_Object *certChainCheckerState,
 421         void *plContext);
 422
 423 #ifdef __cplusplus
 424 }
 425 #endif
 426
 427 #endif /* _PKIX_CHECKER_H */