mirror of
https://github.com/rn10950/RetroZilla.git
synced 2024-11-15 04:00:12 +01:00
302 lines
12 KiB
C
302 lines
12 KiB
C
/* 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 */
|