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