1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,301 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines the public API for libpkix. These are the top-level
1.9 + * functions in the library. They perform the primary operations of this
1.10 + * library: building and validating chains of X.509 certificates.
1.11 + *
1.12 + */
1.13 +
1.14 +#ifndef _PKIX_H
1.15 +#define _PKIX_H
1.16 +
1.17 +#include "pkixt.h"
1.18 +#include "pkix_util.h"
1.19 +#include "pkix_results.h"
1.20 +#include "pkix_certstore.h"
1.21 +#include "pkix_certsel.h"
1.22 +#include "pkix_crlsel.h"
1.23 +#include "pkix_checker.h"
1.24 +#include "pkix_revchecker.h"
1.25 +#include "pkix_pl_system.h"
1.26 +#include "pkix_pl_pki.h"
1.27 +#include "pkix_params.h"
1.28 +
1.29 +#ifdef __cplusplus
1.30 +extern "C" {
1.31 +#endif
1.32 +
1.33 +/* General
1.34 + *
1.35 + * Please refer to the libpkix Programmer's Guide for detailed information
1.36 + * about how to use the libpkix library. Certain key warnings and notices from
1.37 + * that document are repeated here for emphasis.
1.38 + *
1.39 + * All identifiers in this file (and all public identifiers defined in
1.40 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.41 + * within the library begin with "pkix_".
1.42 + *
1.43 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.44 + *
1.45 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.46 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.47 + * shared object. Therefore, the caller should treat this shared object as
1.48 + * read-only and should not modify this shared object. When done using the
1.49 + * shared object, the caller should release the reference to the object by
1.50 + * using the PKIX_PL_Object_DecRef function.
1.51 + *
1.52 + * While a function is executing, if its arguments (or anything referred to by
1.53 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.54 + * is undefined.
1.55 + *
1.56 + */
1.57 +
1.58 +/*
1.59 + * FUNCTION: PKIX_Initialize
1.60 + * DESCRIPTION:
1.61 + *
1.62 + * No PKIX_* types and functions should be used before this function is called
1.63 + * and returns successfully. This function should only be called once. If it
1.64 + * is called more than once, the behavior is undefined.
1.65 + *
1.66 + * NSS applications are expected to call NSS_Init, and need not know that
1.67 + * NSS will call this function (with "platformInitNeeded" set to PKIX_FALSE).
1.68 + * PKIX applications are expected instead to call this function with
1.69 + * "platformInitNeeded" set to PKIX_TRUE.
1.70 + *
1.71 + * This function initializes data structures critical to the operation of
1.72 + * libpkix. It also ensures that the API version (major.minor) desired by the
1.73 + * caller (the "desiredMajorVersion", "minDesiredMinorVersion", and
1.74 + * "maxDesiredMinorVersion") is compatible with the API version supported by
1.75 + * the library. As such, the library must support the "desiredMajorVersion"
1.76 + * of the API and must support a minor version that falls between
1.77 + * "minDesiredMinorVersion" and "maxDesiredMinorVersion", inclusive. If
1.78 + * compatibility exists, the function returns NULL and stores the library's
1.79 + * actual minor version at "pActualMinorVersion" (which may be greater than
1.80 + * "desiredMinorVersion"). If no compatibility exists, the function returns a
1.81 + * PKIX_Error pointer. If the caller wishes to specify that the largest
1.82 + * minor version available should be used, then maxDesiredMinorVersion should
1.83 + * be set to the macro PKIX_MAX_MINOR_VERSION (defined in pkixt.h).
1.84 + *
1.85 + * PARAMETERS:
1.86 + * "platformInitNeeded"
1.87 + * Boolean indicating whether the platform layer initialization code
1.88 + * has previously been run, or should be called from this function.
1.89 + * "desiredMajorVersion"
1.90 + * The major version of the libpkix API the application wishes to use.
1.91 + * "minDesiredMinorVersion"
1.92 + * The minimum minor version of the libpkix API the application wishes
1.93 + * to use.
1.94 + * "maxDesiredMinorVersion"
1.95 + * The maximum minor version of the libpkix API the application wishes
1.96 + * to use.
1.97 + * "pActualMinorVersion"
1.98 + * Address where PKIX_UInt32 will be stored. Must be non-NULL.
1.99 + * "pPlContext"
1.100 + * Address at which platform-specific context pointer is stored. Must
1.101 + * be non-NULL.
1.102 + * THREAD SAFETY:
1.103 + * Not Thread Safe
1.104 + * RETURNS:
1.105 + * Returns NULL if the function succeeds.
1.106 + * Returns an Initialize Error if the function fails in a non-fatal way.
1.107 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.108 + */
1.109 +PKIX_Error *
1.110 +PKIX_Initialize(
1.111 + PKIX_Boolean platformInitNeeded,
1.112 + PKIX_UInt32 desiredMajorVersion,
1.113 + PKIX_UInt32 minDesiredMinorVersion,
1.114 + PKIX_UInt32 maxDesiredMinorVersion,
1.115 + PKIX_UInt32 *pActualMinorVersion,
1.116 + void **pPlContext);
1.117 +
1.118 +/*
1.119 + * FUNCTION: PKIX_Shutdown
1.120 + * DESCRIPTION:
1.121 + *
1.122 + * This function deallocates any memory used by libpkix and shuts down any
1.123 + * ongoing operations. This function should only be called once. If it is
1.124 + * called more than once, the behavior is undefined.
1.125 + *
1.126 + * No PKIX_* types and functions should be used after this function is called
1.127 + * and returns successfully.
1.128 + * PARAMETERS:
1.129 + * "plContext" - Platform-specific context pointer.
1.130 + * THREAD SAFETY:
1.131 + * Not Thread Safe
1.132 + * RETURNS:
1.133 + * Returns NULL if the function succeeds.
1.134 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.135 + */
1.136 +PKIX_Error *
1.137 +PKIX_Shutdown(void *plContext);
1.138 +
1.139 +/*
1.140 + * FUNCTION: PKIX_ValidateChain
1.141 + * DESCRIPTION:
1.142 + *
1.143 + * This function attempts to validate the CertChain that has been set in the
1.144 + * ValidateParams pointed to by "params" using an RFC 3280-compliant
1.145 + * algorithm. If successful, this function returns NULL and stores the
1.146 + * ValidateResult at "pResult", which holds additional information, such as
1.147 + * the policy tree and the target's public key. If unsuccessful, an Error is
1.148 + * returned. Note: This function does not currently support non-blocking I/O.
1.149 + *
1.150 + * If "pVerifyTree" is non-NULL, a chain of VerifyNodes is created which
1.151 + * tracks the results of the validation. That is, either each node in the
1.152 + * chain has a NULL Error component, or the last node contains an Error
1.153 + * which indicates why the validation failed.
1.154 + *
1.155 + * PARAMETERS:
1.156 + * "params"
1.157 + * Address of ValidateParams used to validate CertChain. Must be non-NULL.
1.158 + * "pResult"
1.159 + * Address where object pointer will be stored. Must be non-NULL.
1.160 + * "pVerifyTree"
1.161 + * Address where a VerifyTree is stored, if non-NULL.
1.162 + * "plContext"
1.163 + * Platform-specific context pointer.
1.164 + * THREAD SAFETY:
1.165 + * Thread Safe (See Thread Safety Definitions in Programmer's Guide)
1.166 + * RETURNS:
1.167 + * Returns NULL if the function succeeds.
1.168 + * Returns a Validate Error if the function fails in a non-fatal way.
1.169 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.170 + */
1.171 +PKIX_Error *
1.172 +PKIX_ValidateChain(
1.173 + PKIX_ValidateParams *params,
1.174 + PKIX_ValidateResult **pResult,
1.175 + PKIX_VerifyNode **pVerifyTree,
1.176 + void *plContext);
1.177 +
1.178 +/*
1.179 + * FUNCTION: PKIX_ValidateChain_NB
1.180 + * DESCRIPTION:
1.181 + *
1.182 + * This function is the equivalent of PKIX_ValidateChain, except that it
1.183 + * supports non-blocking I/O. When called with "pNBIOContext" pointing to NULL
1.184 + * it initiates a new chain validation as in PKIX_ValidateChain, ignoring the
1.185 + * value in all input variables except "params". If forced to suspend
1.186 + * processing by a WOULDBLOCK return from some operation, such as a CertStore
1.187 + * request, it stores the platform-dependent I/O context at "pNBIOContext" and
1.188 + * stores other intermediate variables at "pCertIndex", "pAnchorIndex",
1.189 + * "pCheckerIndex", "pRevChecking", and "pCheckers".
1.190 + *
1.191 + * When called subsequently with that non-NULL value at "pNBIOContext", it
1.192 + * relies on those intermediate values to be untouched, and it resumes chain
1.193 + * validation where it left off. Its behavior is undefined if any of the
1.194 + * intermediate values was not preserved.
1.195 + *
1.196 + * PARAMETERS:
1.197 + * "params"
1.198 + * Address of ValidateParams used to validate CertChain. Must be non-NULL.
1.199 + * "pCertIndex"
1.200 + * The UInt32 value of the index to the Cert chain, indicating which Cert
1.201 + * is currently being processed.
1.202 + * "pAnchorIndex"
1.203 + * The UInt32 value of the index to the Anchor chain, indicating which
1.204 + * Trust Anchor is currently being processed.
1.205 + * "pCheckerIndex"
1.206 + * The UInt32 value of the index to the List of CertChainCheckers,
1.207 + * indicating which Checker is currently processing.
1.208 + * "pRevChecking"
1.209 + * The Boolean flag indicating whether normal checking or revocation
1.210 + * checking is occurring for the Cert indicated by "pCertIndex".
1.211 + * "pCheckers"
1.212 + * The address of the List of CertChainCheckers. Must be non-NULL.
1.213 + * "pNBIOContext"
1.214 + * The address of the platform-dependend I/O context. Must be a non-NULL
1.215 + * pointer to a NULL value for the call to initiate chain validation.
1.216 + * "pResult"
1.217 + * Address where ValidateResult object pointer will be stored. Must be
1.218 + * non-NULL.
1.219 + * "pVerifyTree"
1.220 + * Address where a VerifyTree is stored, if non-NULL.
1.221 + * "plContext"
1.222 + * Platform-specific context pointer.
1.223 + * THREAD SAFETY:
1.224 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.225 + * RETURNS:
1.226 + * Returns NULL if the function succeeds.
1.227 + * Returns a VALIDATE Error if the function fails in a non-fatal way.
1.228 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.229 + */PKIX_Error *
1.230 +PKIX_ValidateChain_NB(
1.231 + PKIX_ValidateParams *params,
1.232 + PKIX_UInt32 *pCertIndex,
1.233 + PKIX_UInt32 *pAnchorIndex,
1.234 + PKIX_UInt32 *pCheckerIndex,
1.235 + PKIX_Boolean *pRevChecking,
1.236 + PKIX_List **pCheckers,
1.237 + void **pNBIOContext,
1.238 + PKIX_ValidateResult **pResult,
1.239 + PKIX_VerifyNode **pVerifyTree,
1.240 + void *plContext);
1.241 +
1.242 +/*
1.243 + * FUNCTION: PKIX_BuildChain
1.244 + * DESCRIPTION:
1.245 + *
1.246 + * If called with a NULL "state", this function attempts to build and validate
1.247 + * a CertChain according to the ProcessingParams pointed to by "params", using
1.248 + * an RFC 3280-compliant validation algorithm. If successful, this function
1.249 + * returns NULL and stores the BuildResult at "pResult", which holds the built
1.250 + * CertChain, as well as additional information, such as the policy tree and
1.251 + * the target's public key. If unsuccessful, an Error is returned.
1.252 + *
1.253 + * If the chain building is blocked by a CertStore using non-blocking I/O, this
1.254 + * function stores platform-dependent non-blocking I/O context at
1.255 + * "pNBIOContext", its state at "pState", and NULL at "pResult". The caller
1.256 + * may be able to determine, in a platform-dependent way, when the I/O has
1.257 + * completed. In any case, calling the function again with "pState" containing
1.258 + * the returned value will allow the chain building to resume.
1.259 + *
1.260 + * If chain building is completed, either successfully or unsuccessfully, NULL
1.261 + * is stored at "pNBIOContext".
1.262 + *
1.263 + * If "pVerifyTree" is non-NULL, a tree of VerifyNodes is created which
1.264 + * tracks the results of the building. That is, each node of the tree either
1.265 + * has a NULL Error component, or it is a leaf node and it contains an Error
1.266 + * which indicates why the chain building could not proceed on this branch.
1.267 + *
1.268 + * PARAMETERS:
1.269 + * "params"
1.270 + * Address of ProcessingParams used to build and validate CertChain.
1.271 + * Must be non-NULL.
1.272 + * "pNBIOContext"
1.273 + * Address where platform-dependent information is store if the build
1.274 + * is suspended waiting for non-blocking I/O. Must be non-NULL.
1.275 + * "pState"
1.276 + * Address of BuildChain state. Must be NULL on initial call, and the
1.277 + * value previously returned on subsequent calls.
1.278 + * "pResult"
1.279 + * Address where object pointer will be stored. Must be non-NULL.
1.280 + * "pVerifyTree"
1.281 + * Address where a VerifyTree is stored, if non-NULL.
1.282 + * "plContext"
1.283 + * Platform-specific context pointer.
1.284 + * THREAD SAFETY:
1.285 + * Thread Safe (See Thread Safety Definitions in Programmer's Guide)
1.286 + * RETURNS:
1.287 + * Returns NULL if the function succeeds.
1.288 + * Returns a Build Error if the function fails in a non-fatal way.
1.289 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.290 + */
1.291 +PKIX_Error *
1.292 +PKIX_BuildChain(
1.293 + PKIX_ProcessingParams *params,
1.294 + void **pNBIOContext,
1.295 + void **pState,
1.296 + PKIX_BuildResult **pResult,
1.297 + PKIX_VerifyNode **pVerifyNode,
1.298 + void *plContext);
1.299 +
1.300 +#ifdef __cplusplus
1.301 +}
1.302 +#endif
1.303 +
1.304 +#endif /* _PKIX_H */
