diff options
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix.h')
| -rwxr-xr-x | security/nss/lib/libpkix/include/pkix.h | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix.h b/security/nss/lib/libpkix/include/pkix.h new file mode 100755 index 000000000..4ef3cf1fb --- /dev/null +++ b/security/nss/lib/libpkix/include/pkix.h @@ -0,0 +1,301 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +/* + * This file defines the public API for libpkix. These are the top-level + * functions in the library. They perform the primary operations of this + * library: building and validating chains of X.509 certificates. + * + */ + +#ifndef _PKIX_H +#define _PKIX_H + +#include "pkixt.h" +#include "pkix_util.h" +#include "pkix_results.h" +#include "pkix_certstore.h" +#include "pkix_certsel.h" +#include "pkix_crlsel.h" +#include "pkix_checker.h" +#include "pkix_revchecker.h" +#include "pkix_pl_system.h" +#include "pkix_pl_pki.h" +#include "pkix_params.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* General + * + * Please refer to the libpkix Programmer's Guide for detailed information + * about how to use the libpkix library. Certain key warnings and notices from + * that document are repeated here for emphasis. + * + * All identifiers in this file (and all public identifiers defined in + * libpkix) begin with "PKIX_". Private identifiers only intended for use + * within the library begin with "pkix_". + * + * A function returns NULL upon success, and a PKIX_Error pointer upon failure. + * + * Unless otherwise noted, for all accessor (gettor) functions that return a + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a + * shared object. Therefore, the caller should treat this shared object as + * read-only and should not modify this shared object. When done using the + * shared object, the caller should release the reference to the object by + * using the PKIX_PL_Object_DecRef function. + * + * While a function is executing, if its arguments (or anything referred to by + * its arguments) are modified, free'd, or destroyed, the function's behavior + * is undefined. + * + */ + +/* + * FUNCTION: PKIX_Initialize + * DESCRIPTION: + * + * No PKIX_* types and functions should be used before this function is called + * and returns successfully. This function should only be called once. If it + * is called more than once, the behavior is undefined. + * + * NSS applications are expected to call NSS_Init, and need not know that + * NSS will call this function (with "platformInitNeeded" set to PKIX_FALSE). + * PKIX applications are expected instead to call this function with + * "platformInitNeeded" set to PKIX_TRUE. + * + * This function initializes data structures critical to the operation of + * libpkix. It also ensures that the API version (major.minor) desired by the + * caller (the "desiredMajorVersion", "minDesiredMinorVersion", and + * "maxDesiredMinorVersion") is compatible with the API version supported by + * the library. As such, the library must support the "desiredMajorVersion" + * of the API and must support a minor version that falls between + * "minDesiredMinorVersion" and "maxDesiredMinorVersion", inclusive. If + * compatibility exists, the function returns NULL and stores the library's + * actual minor version at "pActualMinorVersion" (which may be greater than + * "desiredMinorVersion"). If no compatibility exists, the function returns a + * PKIX_Error pointer. If the caller wishes to specify that the largest + * minor version available should be used, then maxDesiredMinorVersion should + * be set to the macro PKIX_MAX_MINOR_VERSION (defined in pkixt.h). + * + * PARAMETERS: + * "platformInitNeeded" + * Boolean indicating whether the platform layer initialization code + * has previously been run, or should be called from this function. + * "desiredMajorVersion" + * The major version of the libpkix API the application wishes to use. + * "minDesiredMinorVersion" + * The minimum minor version of the libpkix API the application wishes + * to use. + * "maxDesiredMinorVersion" + * The maximum minor version of the libpkix API the application wishes + * to use. + * "pActualMinorVersion" + * Address where PKIX_UInt32 will be stored. Must be non-NULL. + * "pPlContext" + * Address at which platform-specific context pointer is stored. Must + * be non-NULL. + * THREAD SAFETY: + * Not Thread Safe + * RETURNS: + * Returns NULL if the function succeeds. + * Returns an Initialize Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Initialize( + PKIX_Boolean platformInitNeeded, + PKIX_UInt32 desiredMajorVersion, + PKIX_UInt32 minDesiredMinorVersion, + PKIX_UInt32 maxDesiredMinorVersion, + PKIX_UInt32 *pActualMinorVersion, + void **pPlContext); + +/* + * FUNCTION: PKIX_Shutdown + * DESCRIPTION: + * + * This function deallocates any memory used by libpkix and shuts down any + * ongoing operations. This function should only be called once. If it is + * called more than once, the behavior is undefined. + * + * No PKIX_* types and functions should be used after this function is called + * and returns successfully. + * PARAMETERS: + * "plContext" - Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_Shutdown(void *plContext); + +/* + * FUNCTION: PKIX_ValidateChain + * DESCRIPTION: + * + * This function attempts to validate the CertChain that has been set in the + * ValidateParams pointed to by "params" using an RFC 3280-compliant + * algorithm. If successful, this function returns NULL and stores the + * ValidateResult at "pResult", which holds additional information, such as + * the policy tree and the target's public key. If unsuccessful, an Error is + * returned. Note: This function does not currently support non-blocking I/O. + * + * If "pVerifyTree" is non-NULL, a chain of VerifyNodes is created which + * tracks the results of the validation. That is, either each node in the + * chain has a NULL Error component, or the last node contains an Error + * which indicates why the validation failed. + * + * PARAMETERS: + * "params" + * Address of ValidateParams used to validate CertChain. Must be non-NULL. + * "pResult" + * Address where object pointer will be stored. Must be non-NULL. + * "pVerifyTree" + * Address where a VerifyTree is stored, if non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (See Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Validate Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_ValidateChain( + PKIX_ValidateParams *params, + PKIX_ValidateResult **pResult, + PKIX_VerifyNode **pVerifyTree, + void *plContext); + +/* + * FUNCTION: PKIX_ValidateChain_NB + * DESCRIPTION: + * + * This function is the equivalent of PKIX_ValidateChain, except that it + * supports non-blocking I/O. When called with "pNBIOContext" pointing to NULL + * it initiates a new chain validation as in PKIX_ValidateChain, ignoring the + * value in all input variables except "params". If forced to suspend + * processing by a WOULDBLOCK return from some operation, such as a CertStore + * request, it stores the platform-dependent I/O context at "pNBIOContext" and + * stores other intermediate variables at "pCertIndex", "pAnchorIndex", + * "pCheckerIndex", "pRevChecking", and "pCheckers". + * + * When called subsequently with that non-NULL value at "pNBIOContext", it + * relies on those intermediate values to be untouched, and it resumes chain + * validation where it left off. Its behavior is undefined if any of the + * intermediate values was not preserved. + * + * PARAMETERS: + * "params" + * Address of ValidateParams used to validate CertChain. Must be non-NULL. + * "pCertIndex" + * The UInt32 value of the index to the Cert chain, indicating which Cert + * is currently being processed. + * "pAnchorIndex" + * The UInt32 value of the index to the Anchor chain, indicating which + * Trust Anchor is currently being processed. + * "pCheckerIndex" + * The UInt32 value of the index to the List of CertChainCheckers, + * indicating which Checker is currently processing. + * "pRevChecking" + * The Boolean flag indicating whether normal checking or revocation + * checking is occurring for the Cert indicated by "pCertIndex". + * "pCheckers" + * The address of the List of CertChainCheckers. Must be non-NULL. + * "pNBIOContext" + * The address of the platform-dependend I/O context. Must be a non-NULL + * pointer to a NULL value for the call to initiate chain validation. + * "pResult" + * Address where ValidateResult object pointer will be stored. Must be + * non-NULL. + * "pVerifyTree" + * Address where a VerifyTree is stored, if non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a VALIDATE Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */PKIX_Error * +PKIX_ValidateChain_NB( + PKIX_ValidateParams *params, + PKIX_UInt32 *pCertIndex, + PKIX_UInt32 *pAnchorIndex, + PKIX_UInt32 *pCheckerIndex, + PKIX_Boolean *pRevChecking, + PKIX_List **pCheckers, + void **pNBIOContext, + PKIX_ValidateResult **pResult, + PKIX_VerifyNode **pVerifyTree, + void *plContext); + +/* + * FUNCTION: PKIX_BuildChain + * DESCRIPTION: + * + * If called with a NULL "state", this function attempts to build and validate + * a CertChain according to the ProcessingParams pointed to by "params", using + * an RFC 3280-compliant validation algorithm. If successful, this function + * returns NULL and stores the BuildResult at "pResult", which holds the built + * CertChain, as well as additional information, such as the policy tree and + * the target's public key. If unsuccessful, an Error is returned. + * + * If the chain building is blocked by a CertStore using non-blocking I/O, this + * function stores platform-dependent non-blocking I/O context at + * "pNBIOContext", its state at "pState", and NULL at "pResult". The caller + * may be able to determine, in a platform-dependent way, when the I/O has + * completed. In any case, calling the function again with "pState" containing + * the returned value will allow the chain building to resume. + * + * If chain building is completed, either successfully or unsuccessfully, NULL + * is stored at "pNBIOContext". + * + * If "pVerifyTree" is non-NULL, a tree of VerifyNodes is created which + * tracks the results of the building. That is, each node of the tree either + * has a NULL Error component, or it is a leaf node and it contains an Error + * which indicates why the chain building could not proceed on this branch. + * + * PARAMETERS: + * "params" + * Address of ProcessingParams used to build and validate CertChain. + * Must be non-NULL. + * "pNBIOContext" + * Address where platform-dependent information is store if the build + * is suspended waiting for non-blocking I/O. Must be non-NULL. + * "pState" + * Address of BuildChain state. Must be NULL on initial call, and the + * value previously returned on subsequent calls. + * "pResult" + * Address where object pointer will be stored. Must be non-NULL. + * "pVerifyTree" + * Address where a VerifyTree is stored, if non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (See Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Build Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_BuildChain( + PKIX_ProcessingParams *params, + void **pNBIOContext, + void **pState, + PKIX_BuildResult **pResult, + PKIX_VerifyNode **pVerifyNode, + void *plContext); + +#ifdef __cplusplus +} +#endif + +#endif /* _PKIX_H */ |