security/nss/lib/libpkix/include/pkix.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 the public API for libpkix. These are the top-level
  39  * functions in the library. They perform the primary operations of this
  40  * library: building and validating chains of X.509 certificates.
  41  *
  42  */
  43
  44 #ifndef _PKIX_H
  45 #define _PKIX_H
  46
  47 #include "pkixt.h"
  48 #include "pkix_util.h"
  49 #include "pkix_params.h"
  50 #include "pkix_results.h"
  51 #include "pkix_certstore.h"
  52 #include "pkix_certsel.h"
  53 #include "pkix_crlsel.h"
  54 #include "pkix_checker.h"
  55 #include "pkix_revchecker.h"
  56 #include "pkix_pl_system.h"
  57 #include "pkix_pl_pki.h"
  58
  59 #ifdef __cplusplus
  60 extern "C" {
  61 #endif
  62
  63 /* General
  64  *
  65  * Please refer to the libpkix Programmer's Guide for detailed information
  66  * about how to use the libpkix library. Certain key warnings and notices from
  67  * that document are repeated here for emphasis.
  68  *
  69  * All identifiers in this file (and all public identifiers defined in
  70  * libpkix) begin with "PKIX_". Private identifiers only intended for use
  71  * within the library begin with "pkix_".
  72  *
  73  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
  74  *
  75  * Unless otherwise noted, for all accessor (gettor) functions that return a
  76  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
  77  * shared object. Therefore, the caller should treat this shared object as
  78  * read-only and should not modify this shared object. When done using the
  79  * shared object, the caller should release the reference to the object by
  80  * using the PKIX_PL_Object_DecRef function.
  81  *
  82  * While a function is executing, if its arguments (or anything referred to by
  83  * its arguments) are modified, free'd, or destroyed, the function's behavior
  84  * is undefined.
  85  *
  86  */
  87
  88 /*
  89  * FUNCTION: PKIX_Initialize
  90  * DESCRIPTION:
  91  *
  92  * No PKIX_* types and functions should be used before this function is called
  93  * and returns successfully. This function should only be called once. If it
  94  * is called more than once, the behavior is undefined.
  95  *
  96  * NSS applications are expected to call NSS_Init, and need not know that
  97  * NSS will call this function (with "platformInitNeeded" set to PKIX_FALSE).
  98  * PKIX applications are expected instead to call this function with
  99  * "platformInitNeeded" set to PKIX_TRUE.
 100  *
 101  * This function initializes data structures critical to the operation of
 102  * libpkix. It also ensures that the API version (major.minor) desired by the
 103  * caller (the "desiredMajorVersion", "minDesiredMinorVersion", and
 104  * "maxDesiredMinorVersion") is compatible with the API version supported by
 105  * the library. As such, the library must support the "desiredMajorVersion"
 106  * of the API and must support a minor version that falls between
 107  * "minDesiredMinorVersion" and "maxDesiredMinorVersion", inclusive. If
 108  * compatibility exists, the function returns NULL and stores the library's
 109  * actual minor version at "pActualMinorVersion" (which may be greater than
 110  * "desiredMinorVersion"). If no compatibility exists, the function returns a
 111  * PKIX_Error pointer. If the caller wishes to specify that the largest
 112  * minor version available should be used, then maxDesiredMinorVersion should
 113  * be set to the macro PKIX_MAX_MINOR_VERSION (defined in pkixt.h).
 114  *
 115  * PARAMETERS:
 116  *  "platformInitNeeded"
 117  *      Boolean indicating whether the platform layer initialization code
 118  *      has previously been run, or should be called from this function.
 119  *  "desiredMajorVersion"
 120  *      The major version of the libpkix API the application wishes to use.
 121  *  "minDesiredMinorVersion"
 122  *      The minimum minor version of the libpkix API the application wishes
 123  *      to use.
 124  *  "maxDesiredMinorVersion"
 125  *      The maximum minor version of the libpkix API the application wishes
 126  *      to use.
 127  *  "pActualMinorVersion"
 128  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
 129  *  "pPlContext"
 130  *      Address at which platform-specific context pointer is stored. Must
 131  *      be non-NULL.
 132  * THREAD SAFETY:
 133  *  Not Thread Safe
 134  * RETURNS:
 135  *  Returns NULL if the function succeeds.
 136  *  Returns an Initialize 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 PKIX_Error *
 140 PKIX_Initialize(
 141         PKIX_Boolean platformInitNeeded,
 142         PKIX_UInt32 desiredMajorVersion,
 143         PKIX_UInt32 minDesiredMinorVersion,
 144         PKIX_UInt32 maxDesiredMinorVersion,
 145         PKIX_UInt32 *pActualMinorVersion,
 146         void **pPlContext);
 147
 148 /*
 149  * FUNCTION: PKIX_Shutdown
 150  * DESCRIPTION:
 151  *
 152  *  This function deallocates any memory used by libpkix and shuts down any
 153  *  ongoing operations. This function should only be called once. If it is
 154  *  called more than once, the behavior is undefined.
 155  *
 156  *  No PKIX_* types and functions should be used after this function is called
 157  *  and returns successfully.
 158  * PARAMETERS:
 159  *  "plContext" - Platform-specific context pointer.
 160  * THREAD SAFETY:
 161  *  Not Thread Safe
 162  * RETURNS:
 163  *  Returns NULL if the function succeeds.
 164  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 165  */
 166 PKIX_Error *
 167 PKIX_Shutdown(void *plContext);
 168
 169 /*
 170  * FUNCTION: PKIX_ValidateChain
 171  * DESCRIPTION:
 172  *
 173  *  This function attempts to validate the CertChain that has been set in the
 174  *  ValidateParams pointed to by "params" using an RFC 3280-compliant
 175  *  algorithm. If successful, this function returns NULL and stores the
 176  *  ValidateResult at "pResult", which holds additional information, such as
 177  *  the policy tree and the target's public key. If unsuccessful, an Error is
 178  *  returned. Note: This function does not currently support non-blocking I/O.
 179  *
 180  *  If "pVerifyTree" is non-NULL, a chain of VerifyNodes is created which
 181  *  tracks the results of the validation. That is, either each node in the
 182  *  chain has a NULL Error component, or the last node contains an Error
 183  *  which indicates why the validation failed.
 184  *
 185  * PARAMETERS:
 186  *  "params"
 187  *      Address of ValidateParams used to validate CertChain. Must be non-NULL.
 188  *  "pResult"
 189  *      Address where object pointer will be stored. Must be non-NULL.
 190  *  "pVerifyTree"
 191  *      Address where a VerifyTree is stored, if non-NULL.
 192  *  "plContext"
 193  *      Platform-specific context pointer.
 194  * THREAD SAFETY:
 195  *  Thread Safe (See Thread Safety Definitions in Programmer's Guide)
 196  * RETURNS:
 197  *  Returns NULL if the function succeeds.
 198  *  Returns a Validate Error if the function fails in a non-fatal way.
 199  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 200  */
 201 PKIX_Error *
 202 PKIX_ValidateChain(
 203         PKIX_ValidateParams *params,
 204         PKIX_ValidateResult **pResult,
 205         PKIX_VerifyNode **pVerifyTree,
 206         void *plContext);
 207
 208 /*
 209  * FUNCTION: PKIX_ValidateChain_NB
 210  * DESCRIPTION:
 211  *
 212  *  This function is the equivalent of PKIX_ValidateChain, except that it
 213  *  supports non-blocking I/O. When called with "pNBIOContext" pointing to NULL
 214  *  it initiates a new chain validation as in PKIX_ValidateChain, ignoring the
 215  *  value in all input variables except "params". If forced to suspend
 216  *  processing by a WOULDBLOCK return from some operation, such as a CertStore
 217  *  request, it stores the platform-dependent I/O context at "pNBIOContext" and
 218  *  stores other intermediate variables at "pCertIndex", "pAnchorIndex",
 219  *  "pCheckerIndex", "pRevChecking", and "pCheckers".
 220  *
 221  *  When called subsequently with that non-NULL value at "pNBIOContext", it
 222  *  relies on those intermediate values to be untouched, and it resumes chain
 223  *  validation where it left off. Its behavior is undefined if any of the
 224  *  intermediate values was not preserved.
 225  *
 226  * PARAMETERS:
 227  *  "params"
 228  *      Address of ValidateParams used to validate CertChain. Must be non-NULL.
 229  *  "pCertIndex"
 230  *      The UInt32 value of the index to the Cert chain, indicating which Cert
 231  *      is currently being processed.
 232  *  "pAnchorIndex"
 233  *      The UInt32 value of the index to the Anchor chain, indicating which
 234  *      Trust Anchor is currently being processed.
 235  *  "pCheckerIndex"
 236  *      The UInt32 value of the index to the List of CertChainCheckers,
 237  *      indicating which Checker is currently processing.
 238  *  "pRevChecking"
 239  *      The Boolean flag indicating whether normal checking or revocation
 240  *      checking is occurring for the Cert indicated by "pCertIndex".
 241  *  "pCheckers"
 242  *      The address of the List of CertChainCheckers. Must be non-NULL.
 243  *  "pNBIOContext"
 244  *      The address of the platform-dependend I/O context. Must be a non-NULL
 245  *      pointer to a NULL value for the call to initiate chain validation.
 246  *  "pResult"
 247  *      Address where ValidateResult object pointer will be stored. Must be
 248  *      non-NULL.
 249  *  "pVerifyTree"
 250  *      Address where a VerifyTree is stored, if non-NULL.
 251  *  "plContext"
 252  *      Platform-specific context pointer.
 253  * THREAD SAFETY:
 254  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 255  * RETURNS:
 256  *  Returns NULL if the function succeeds.
 257  *  Returns a VALIDATE Error if the function fails in a non-fatal way.
 258  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 259  */PKIX_Error *
 260 PKIX_ValidateChain_NB(
 261         PKIX_ValidateParams *params,
 262         PKIX_UInt32 *pCertIndex,
 263         PKIX_UInt32 *pAnchorIndex,
 264         PKIX_UInt32 *pCheckerIndex,
 265         PKIX_Boolean *pRevChecking,
 266         PKIX_List **pCheckers,
 267         void **pNBIOContext,
 268         PKIX_ValidateResult **pResult,
 269         PKIX_VerifyNode **pVerifyTree,
 270         void *plContext);
 271
 272 /*
 273  * FUNCTION: PKIX_BuildChain
 274  * DESCRIPTION:
 275  *
 276  *  If called with a NULL "state", this function attempts to build and validate
 277  *  a CertChain according to the ProcessingParams pointed to by "params", using
 278  *  an RFC 3280-compliant validation algorithm. If successful, this function
 279  *  returns NULL and stores the BuildResult at "pResult", which holds the built
 280  *  CertChain, as well as additional information, such as the policy tree and
 281  *  the target's public key. If unsuccessful, an Error is returned.
 282  *
 283  *  If the chain building is blocked by a CertStore using non-blocking I/O, this
 284  *  function stores platform-dependent non-blocking I/O context at
 285  *  "pNBIOContext", its state at "pState", and NULL at "pResult". The caller
 286  *  may be able to determine, in a platform-dependent way, when the I/O has
 287  *  completed. In any case, calling the function again with "pState" containing
 288  *  the returned value will allow the chain building to resume.
 289  *
 290  *  If chain building is completed, either successfully or unsuccessfully, NULL
 291  *  is stored at "pNBIOContext".
 292  *
 293  *  If "pVerifyTree" is non-NULL, a tree of VerifyNodes is created which
 294  *  tracks the results of the building. That is, each node of the tree either
 295  *  has a NULL Error component, or it is a leaf node and it contains an Error
 296  *  which indicates why the chain building could not proceed on this branch.
 297  *
 298  * PARAMETERS:
 299  *  "params"
 300  *      Address of ProcessingParams used to build and validate CertChain.
 301  *      Must be non-NULL.
 302  *  "pNBIOContext"
 303  *      Address where platform-dependent information is store if the build
 304  *      is suspended waiting for non-blocking I/O. Must be non-NULL.
 305  *  "pState"
 306  *      Address of BuildChain state. Must be NULL on initial call, and the
 307  *      value previously returned on subsequent calls.
 308  *  "pResult"
 309  *      Address where object pointer will be stored. Must be non-NULL.
 310  *  "pVerifyTree"
 311  *      Address where a VerifyTree is stored, if non-NULL.
 312  *  "plContext"
 313  *      Platform-specific context pointer.
 314  * THREAD SAFETY:
 315  *  Thread Safe (See Thread Safety Definitions in Programmer's Guide)
 316  * RETURNS:
 317  *  Returns NULL if the function succeeds.
 318  *  Returns a Build Error if the function fails in a non-fatal way.
 319  *  Returns a Fatal Error if the function fails in an unrecoverable way.
 320  */
 321 PKIX_Error *
 322 PKIX_BuildChain(
 323         PKIX_ProcessingParams *params,
 324         void **pNBIOContext,
 325         void **pState,
 326         PKIX_BuildResult **pResult,
 327         PKIX_VerifyNode **pVerifyNode,
 328         void *plContext);
 329
 330 #ifdef __cplusplus
 331 }
 332 #endif
 333
 334 #endif /* _PKIX_H */