| /* 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 */ |