summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/libpkix/include/pkix_checker.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_checker.h')
-rwxr-xr-xsecurity/nss/lib/libpkix/include/pkix_checker.h394
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 100755
index 000000000..97e29a840
--- /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 */