diff options
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_checker.h')
| -rw-r--r-- | security/nss/lib/libpkix/include/pkix_checker.h | 394 |
1 files changed, 394 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_checker.h b/security/nss/lib/libpkix/include/pkix_checker.h new file mode 100644 index 0000000000..97e29a8403 --- /dev/null +++ b/security/nss/lib/libpkix/include/pkix_checker.h @@ -0,0 +1,394 @@ +/* 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 functions associated with the PKIX_CertChainChecker type. + * + */ + +#ifndef _PKIX_CHECKER_H +#define _PKIX_CHECKER_H + +#include "pkixt.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. + * + */ + +/* PKIX_CertChainChecker + * + * PKIX_CertChainCheckers provide a standard way for the caller to insert their + * own custom checks to validate certificates. This may be useful in many + * scenarios, including when the caller wishes to validate private certificate + * extensions. The CheckCallback allows custom certificate processing to take + * place. Additionally, a CertChainChecker can optionally maintain state + * between successive calls to the CheckCallback. This certChainCheckerState + * must be an Object (although any object type), allowing it to be + * reference-counted and allowing it to provide the standard Object functions + * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes + * their CertChainChecker to be used during chain building, their + * certChainCheckerState object must implement an appropriate Duplicate + * function. The builder uses this Duplicate function when backtracking. + * + * Once the caller has created a CertChainChecker object, the caller then + * specifies a CertChainChecker object in a ProcessingParams object + * and passes the ProcessingParams object to PKIX_ValidateChain or + * PKIX_BuildChain, which uses the objects to call the user's callback + * functions as needed during the validation or building process. + * + * A CertChainChecker may be presented certificates in the "reverse" direction + * (from trust anchor to target) or in the "forward" direction (from target to + * trust anchor). All CertChainCheckers must support "reverse checking", while + * support for "forward checking" is optional, but recommended. If "forward + * checking" is not supported, building chains may be much less efficient. The + * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to + * determine whether forward checking is supported, and the + * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to + * determine whether the CertChainChecker has been initialized to expect the + * certificates to be presented in the "forward" direction. + */ + +/* + * FUNCTION: PKIX_CertChainChecker_CheckCallback + * DESCRIPTION: + * + * This callback function checks whether the specified Cert pointed to by + * "cert" is valid using "checker's" internal certChainCheckerState (if any) + * and removes the critical extensions that it processes (if any) from the + * List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions". + * If the checker finds that the certificate is not valid, an Error pointer is + * returned. + * + * If the checker uses non-blocking I/O, the address of a platform-dependent + * non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext", + * which the caller may use, in a platform-dependent way, to wait, poll, or + * otherwise determine when to try again. If the checker does not use + * non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL + * value was stored, on a subsequent call the checker will attempt to complete + * the pending I/O and, if successful, NULL will be stored at "pNBIOContext". + * + * PARAMETERS: + * "checker" + * Address of CertChainChecker whose certChainCheckerState and + * CheckCallback logic is to be used. Must be non-NULL. + * "cert" + * Address of Cert that is to be validated using "checker". + * Must be non-NULL. + * "unresolvedCriticalExtensions" + * Address of List of OIDs that represents the critical certificate + * extensions that have yet to be resolved. This parameter may be + * modified during the function call. Must be non-NULL. + * "pNBIOContext" + * Address at which is stored a platform-dependent structure indicating + * whether checking was suspended for non-blocking I/O. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe + * + * Multiple threads must be able to safely call this function without + * worrying about conflicts, even if they're operating on the same object. + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertChainChecker Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +typedef PKIX_Error * +(*PKIX_CertChainChecker_CheckCallback)( + PKIX_CertChainChecker *checker, + PKIX_PL_Cert *cert, + PKIX_List *unresolvedCriticalExtensions, /* list of PKIX_PL_OID */ + void **pNBIOContext, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_Create + * DESCRIPTION: + * + * Creates a new CertChainChecker and stores it at "pChecker". The new + * CertChainChecker uses the CheckCallback pointed to by "callback" as its + * callback function. It uses the Object pointed to by "initialState" (if + * any) as its initial state. As noted above, the initial state Object must + * provide a custom implementation of PKIX_PL_Object_Duplicate if the + * CertChainChecker is to be used during certificate chain building. + * + * A CertChainChecker may be presented certificates in the "reverse" + * direction (from trust anchor to target) or in the "forward" direction + * (from target to trust anchor). All CertChainCheckers must support + * "reverse checking", while support for "forward checking" is optional. The + * CertChainChecker is initialized with two Boolean flags that deal with this + * distinction: "forwardCheckingSupported" and "forwardDirectionExpected". + * If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that + * this CertChainChecker is capable of checking certificates in the "forward" + * direction (as well as the "reverse" direction, which all CertChainCheckers + * MUST support). The "forwardDirectionExpected" Boolean flag indicates in + * which direction the CertChainChecker should expect the certificates to be + * presented. This is particularly useful for CertChainCheckers that are + * capable of checking in either the "forward" direction or the "reverse" + * direction, but have different processing steps depending on the direction. + * + * The CertChainChecker also uses the List of OIDs pointed to by "extensions" + * as the supported certificate extensions. All certificate extensions that + * the CertChainChecker might possibly recognize and be able to process + * should be included in the List of supported extensions. If "checker" does + * not recognize or process any certificate extensions, "extensions" should + * be set to NULL. + * + * PARAMETERS: + * "callback" + * The CheckCallback function to be used. Must be non-NULL. + * "forwardCheckingSupported" + * A Boolean value indicating whether or not this CertChainChecker is + * capable of checking certificates in the "forward" direction. + * "forwardDirectionExpected" + * A Boolean value indicating whether or not this CertChainChecker should + * be used to check in the "forward" direction. + * "extensions" + * Address of List of OIDs representing the supported extensions. + * "initialState" + * Address of Object representing the CertChainChecker's initial state + * (if any). + * "pChecker" + * Address where object pointer will be stored. Must be 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 CertChainChecker 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_CertChainChecker_Create( + PKIX_CertChainChecker_CheckCallback callback, + PKIX_Boolean forwardCheckingSupported, + PKIX_Boolean forwardDirectionExpected, + PKIX_List *extensions, /* list of PKIX_PL_OID */ + PKIX_PL_Object *initialState, + PKIX_CertChainChecker **pChecker, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_GetCheckCallback + * DESCRIPTION: + * + * Retrieves a pointer to "checker's" Check callback function and puts it in + * "pCallback". + * + * PARAMETERS: + * "checker" + * The CertChainChecker whose Check callback is desired. Must be non-NULL. + * "pCallback" + * Address where Check callback function pointer will be stored. + * Must be 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 CertChainChecker 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_CertChainChecker_GetCheckCallback( + PKIX_CertChainChecker *checker, + PKIX_CertChainChecker_CheckCallback *pCallback, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported + * DESCRIPTION: + * + * Checks whether forward checking is supported by the CertChainChecker + * pointed to by "checker" and stores the Boolean result at + * "pForwardCheckingSupported". + * + * A CertChainChecker may be presented certificates in the "reverse" + * direction (from trust anchor to target) or in the "forward" direction + * (from target to trust anchor). All CertChainCheckers must support + * "reverse checking", while support for "forward checking" is optional. This + * function is used to determine whether forward checking is supported. + * + * PARAMETERS: + * "checker" + * The CertChainChecker whose ability to validate certificates in the + * "forward" direction is to be checked. Must be non-NULL. + * "pForwardCheckingSupported" + * Destination of the Boolean result. Must be 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 CertChainChecker 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_CertChainChecker_IsForwardCheckingSupported( + PKIX_CertChainChecker *checker, + PKIX_Boolean *pForwardCheckingSupported, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected + * DESCRIPTION: + * + * Checks whether the CertChainChecker pointed to by "checker" has been + * initialized to expect the certificates to be presented in the "forward" + * direction and stores the Boolean result at "pForwardDirectionExpected". + * + * A CertChainChecker may be presented certificates in the "reverse" + * direction (from trust anchor to target) or in the "forward" direction + * (from target to trust anchor). All CertChainCheckers must support + * "reverse checking", while support for "forward checking" is optional. This + * function is used to determine in which direction the CertChainChecker + * expects the certificates to be presented. + * + * PARAMETERS: + * "checker" + * The CertChainChecker that has been initialized to expect certificates + * in either the "forward" or "reverse" directions. Must be non-NULL. + * "pForwardDirectionExpected" + * Destination of the Boolean result. Must be 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 CertChainChecker 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_CertChainChecker_IsForwardDirectionExpected( + PKIX_CertChainChecker *checker, + PKIX_Boolean *pForwardDirectionExpected, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions + * DESCRIPTION: + * + * Retrieves a pointer to a List of OIDs (each OID corresponding to a + * certificate extension supported by the CertChainChecker pointed to by + * "checker") and stores it at "pExtensions". All certificate extensions that + * the CertChainChecker might possibly recognize and be able to process + * should be included in the List of supported extensions. If "checker" does + * not recognize or process any certificate extensions, this function stores + * NULL at "pExtensions". + * + * Note that the List returned by this function is immutable. + * + * PARAMETERS: + * "checker" + * Address of CertChainChecker whose supported extension OIDs are to be + * stored. Must be non-NULL. + * "pExtensions" + * Address where object pointer will be stored. Must be 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 CertChainChecker 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_CertChainChecker_GetSupportedExtensions( + PKIX_CertChainChecker *checker, + PKIX_List **pExtensions, /* list of PKIX_PL_OID */ + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState + * DESCRIPTION: + * + * Retrieves a pointer to a PKIX_PL_Object representing the internal state + * (if any) of the CertChainChecker pointed to by "checker" and stores it at + * "pCertChainCheckerState". + * + * PARAMETERS: + * "checker" + * Address of CertChainChecker whose state is to be stored. + * Must be non-NULL. + * "pCertChainCheckerState" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Conditionally Thread Safe + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertChainChecker 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_CertChainChecker_GetCertChainCheckerState( + PKIX_CertChainChecker *checker, + PKIX_PL_Object **pCertChainCheckerState, + void *plContext); + +/* + * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState + * DESCRIPTION: + * + * Sets the internal state of the CertChainChecker pointed to by "checker" + * using the Object pointed to by "certChainCheckerState". If "checker" needs + * a NULL internal state, "certChainCheckerState" should be set to NULL. + * + * PARAMETERS: + * "checker" + * Address of CertChainChecker whose state is to be set. Must be non-NULL. + * "certChainCheckerState" + * Address of Object representing internal state. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Not Thread Safe - assumes exclusive access to "checker" + * (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertChainChecker 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_CertChainChecker_SetCertChainCheckerState( + PKIX_CertChainChecker *checker, + PKIX_PL_Object *certChainCheckerState, + void *plContext); + +#ifdef __cplusplus +} +#endif + +#endif /* _PKIX_CHECKER_H */ |