Mercurial > trustbridge > nss-cmake-static
view nss/lib/libpkix/include/pkix.h @ 0:1e5118fa0cb1
This is NSS with a Cmake Buildsyste
To compile a static NSS library for Windows we've used the
Chromium-NSS fork and added a Cmake buildsystem to compile
it statically for Windows. See README.chromium for chromium
changes and README.trustbridge for our modifications.
author | Andre Heinecke <andre.heinecke@intevation.de> |
---|---|
date | Mon, 28 Jul 2014 10:47:06 +0200 (2014-07-28) |
parents | |
children |
line wrap: on
line source
/* 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 */