1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_checker.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,394 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +/*
1.8 + * This file defines functions associated with the PKIX_CertChainChecker type.
1.9 + *
1.10 + */
1.11 +
1.12 +#ifndef _PKIX_CHECKER_H
1.13 +#define _PKIX_CHECKER_H
1.14 +
1.15 +#include "pkixt.h"
1.16 +
1.17 +#ifdef __cplusplus
1.18 +extern "C" {
1.19 +#endif
1.20 +
1.21 +/* General
1.22 + *
1.23 + * Please refer to the libpkix Programmer's Guide for detailed information
1.24 + * about how to use the libpkix library. Certain key warnings and notices from
1.25 + * that document are repeated here for emphasis.
1.26 + *
1.27 + * All identifiers in this file (and all public identifiers defined in
1.28 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.29 + * within the library begin with "pkix_".
1.30 + *
1.31 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.32 + *
1.33 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.34 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.35 + * shared object. Therefore, the caller should treat this shared object as
1.36 + * read-only and should not modify this shared object. When done using the
1.37 + * shared object, the caller should release the reference to the object by
1.38 + * using the PKIX_PL_Object_DecRef function.
1.39 + *
1.40 + * While a function is executing, if its arguments (or anything referred to by
1.41 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.42 + * is undefined.
1.43 + *
1.44 + */
1.45 +
1.46 +/* PKIX_CertChainChecker
1.47 + *
1.48 + * PKIX_CertChainCheckers provide a standard way for the caller to insert their
1.49 + * own custom checks to validate certificates. This may be useful in many
1.50 + * scenarios, including when the caller wishes to validate private certificate
1.51 + * extensions. The CheckCallback allows custom certificate processing to take
1.52 + * place. Additionally, a CertChainChecker can optionally maintain state
1.53 + * between successive calls to the CheckCallback. This certChainCheckerState
1.54 + * must be an Object (although any object type), allowing it to be
1.55 + * reference-counted and allowing it to provide the standard Object functions
1.56 + * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes
1.57 + * their CertChainChecker to be used during chain building, their
1.58 + * certChainCheckerState object must implement an appropriate Duplicate
1.59 + * function. The builder uses this Duplicate function when backtracking.
1.60 + *
1.61 + * Once the caller has created a CertChainChecker object, the caller then
1.62 + * specifies a CertChainChecker object in a ProcessingParams object
1.63 + * and passes the ProcessingParams object to PKIX_ValidateChain or
1.64 + * PKIX_BuildChain, which uses the objects to call the user's callback
1.65 + * functions as needed during the validation or building process.
1.66 + *
1.67 + * A CertChainChecker may be presented certificates in the "reverse" direction
1.68 + * (from trust anchor to target) or in the "forward" direction (from target to
1.69 + * trust anchor). All CertChainCheckers must support "reverse checking", while
1.70 + * support for "forward checking" is optional, but recommended. If "forward
1.71 + * checking" is not supported, building chains may be much less efficient. The
1.72 + * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to
1.73 + * determine whether forward checking is supported, and the
1.74 + * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to
1.75 + * determine whether the CertChainChecker has been initialized to expect the
1.76 + * certificates to be presented in the "forward" direction.
1.77 + */
1.78 +
1.79 +/*
1.80 + * FUNCTION: PKIX_CertChainChecker_CheckCallback
1.81 + * DESCRIPTION:
1.82 + *
1.83 + * This callback function checks whether the specified Cert pointed to by
1.84 + * "cert" is valid using "checker's" internal certChainCheckerState (if any)
1.85 + * and removes the critical extensions that it processes (if any) from the
1.86 + * List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions".
1.87 + * If the checker finds that the certificate is not valid, an Error pointer is
1.88 + * returned.
1.89 + *
1.90 + * If the checker uses non-blocking I/O, the address of a platform-dependent
1.91 + * non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext",
1.92 + * which the caller may use, in a platform-dependent way, to wait, poll, or
1.93 + * otherwise determine when to try again. If the checker does not use
1.94 + * non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL
1.95 + * value was stored, on a subsequent call the checker will attempt to complete
1.96 + * the pending I/O and, if successful, NULL will be stored at "pNBIOContext".
1.97 + *
1.98 + * PARAMETERS:
1.99 + * "checker"
1.100 + * Address of CertChainChecker whose certChainCheckerState and
1.101 + * CheckCallback logic is to be used. Must be non-NULL.
1.102 + * "cert"
1.103 + * Address of Cert that is to be validated using "checker".
1.104 + * Must be non-NULL.
1.105 + * "unresolvedCriticalExtensions"
1.106 + * Address of List of OIDs that represents the critical certificate
1.107 + * extensions that have yet to be resolved. This parameter may be
1.108 + * modified during the function call. Must be non-NULL.
1.109 + * "pNBIOContext"
1.110 + * Address at which is stored a platform-dependent structure indicating
1.111 + * whether checking was suspended for non-blocking I/O. Must be non-NULL.
1.112 + * "plContext"
1.113 + * Platform-specific context pointer.
1.114 + * THREAD SAFETY:
1.115 + * Thread Safe
1.116 + *
1.117 + * Multiple threads must be able to safely call this function without
1.118 + * worrying about conflicts, even if they're operating on the same object.
1.119 + * RETURNS:
1.120 + * Returns NULL if the function succeeds.
1.121 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.122 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.123 + */
1.124 +typedef PKIX_Error *
1.125 +(*PKIX_CertChainChecker_CheckCallback)(
1.126 + PKIX_CertChainChecker *checker,
1.127 + PKIX_PL_Cert *cert,
1.128 + PKIX_List *unresolvedCriticalExtensions, /* list of PKIX_PL_OID */
1.129 + void **pNBIOContext,
1.130 + void *plContext);
1.131 +
1.132 +/*
1.133 + * FUNCTION: PKIX_CertChainChecker_Create
1.134 + * DESCRIPTION:
1.135 + *
1.136 + * Creates a new CertChainChecker and stores it at "pChecker". The new
1.137 + * CertChainChecker uses the CheckCallback pointed to by "callback" as its
1.138 + * callback function. It uses the Object pointed to by "initialState" (if
1.139 + * any) as its initial state. As noted above, the initial state Object must
1.140 + * provide a custom implementation of PKIX_PL_Object_Duplicate if the
1.141 + * CertChainChecker is to be used during certificate chain building.
1.142 + *
1.143 + * A CertChainChecker may be presented certificates in the "reverse"
1.144 + * direction (from trust anchor to target) or in the "forward" direction
1.145 + * (from target to trust anchor). All CertChainCheckers must support
1.146 + * "reverse checking", while support for "forward checking" is optional. The
1.147 + * CertChainChecker is initialized with two Boolean flags that deal with this
1.148 + * distinction: "forwardCheckingSupported" and "forwardDirectionExpected".
1.149 + * If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that
1.150 + * this CertChainChecker is capable of checking certificates in the "forward"
1.151 + * direction (as well as the "reverse" direction, which all CertChainCheckers
1.152 + * MUST support). The "forwardDirectionExpected" Boolean flag indicates in
1.153 + * which direction the CertChainChecker should expect the certificates to be
1.154 + * presented. This is particularly useful for CertChainCheckers that are
1.155 + * capable of checking in either the "forward" direction or the "reverse"
1.156 + * direction, but have different processing steps depending on the direction.
1.157 + *
1.158 + * The CertChainChecker also uses the List of OIDs pointed to by "extensions"
1.159 + * as the supported certificate extensions. All certificate extensions that
1.160 + * the CertChainChecker might possibly recognize and be able to process
1.161 + * should be included in the List of supported extensions. If "checker" does
1.162 + * not recognize or process any certificate extensions, "extensions" should
1.163 + * be set to NULL.
1.164 + *
1.165 + * PARAMETERS:
1.166 + * "callback"
1.167 + * The CheckCallback function to be used. Must be non-NULL.
1.168 + * "forwardCheckingSupported"
1.169 + * A Boolean value indicating whether or not this CertChainChecker is
1.170 + * capable of checking certificates in the "forward" direction.
1.171 + * "forwardDirectionExpected"
1.172 + * A Boolean value indicating whether or not this CertChainChecker should
1.173 + * be used to check in the "forward" direction.
1.174 + * "extensions"
1.175 + * Address of List of OIDs representing the supported extensions.
1.176 + * "initialState"
1.177 + * Address of Object representing the CertChainChecker's initial state
1.178 + * (if any).
1.179 + * "pChecker"
1.180 + * Address where object pointer will be stored. Must be non-NULL.
1.181 + * "plContext"
1.182 + * Platform-specific context pointer.
1.183 + * THREAD SAFETY:
1.184 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.185 + * RETURNS:
1.186 + * Returns NULL if the function succeeds.
1.187 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.188 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.189 + */
1.190 +PKIX_Error *
1.191 +PKIX_CertChainChecker_Create(
1.192 + PKIX_CertChainChecker_CheckCallback callback,
1.193 + PKIX_Boolean forwardCheckingSupported,
1.194 + PKIX_Boolean forwardDirectionExpected,
1.195 + PKIX_List *extensions, /* list of PKIX_PL_OID */
1.196 + PKIX_PL_Object *initialState,
1.197 + PKIX_CertChainChecker **pChecker,
1.198 + void *plContext);
1.199 +
1.200 +/*
1.201 + * FUNCTION: PKIX_CertChainChecker_GetCheckCallback
1.202 + * DESCRIPTION:
1.203 + *
1.204 + * Retrieves a pointer to "checker's" Check callback function and puts it in
1.205 + * "pCallback".
1.206 + *
1.207 + * PARAMETERS:
1.208 + * "checker"
1.209 + * The CertChainChecker whose Check callback is desired. Must be non-NULL.
1.210 + * "pCallback"
1.211 + * Address where Check callback function pointer will be stored.
1.212 + * Must be non-NULL.
1.213 + * "plContext"
1.214 + * Platform-specific context pointer.
1.215 + * THREAD SAFETY:
1.216 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.217 + * RETURNS:
1.218 + * Returns NULL if the function succeeds.
1.219 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.220 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.221 + */
1.222 +PKIX_Error *
1.223 +PKIX_CertChainChecker_GetCheckCallback(
1.224 + PKIX_CertChainChecker *checker,
1.225 + PKIX_CertChainChecker_CheckCallback *pCallback,
1.226 + void *plContext);
1.227 +
1.228 +/*
1.229 + * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported
1.230 + * DESCRIPTION:
1.231 + *
1.232 + * Checks whether forward checking is supported by the CertChainChecker
1.233 + * pointed to by "checker" and stores the Boolean result at
1.234 + * "pForwardCheckingSupported".
1.235 + *
1.236 + * A CertChainChecker may be presented certificates in the "reverse"
1.237 + * direction (from trust anchor to target) or in the "forward" direction
1.238 + * (from target to trust anchor). All CertChainCheckers must support
1.239 + * "reverse checking", while support for "forward checking" is optional. This
1.240 + * function is used to determine whether forward checking is supported.
1.241 + *
1.242 + * PARAMETERS:
1.243 + * "checker"
1.244 + * The CertChainChecker whose ability to validate certificates in the
1.245 + * "forward" direction is to be checked. Must be non-NULL.
1.246 + * "pForwardCheckingSupported"
1.247 + * Destination of the Boolean result. Must be non-NULL.
1.248 + * "plContext"
1.249 + * Platform-specific context pointer.
1.250 + * THREAD SAFETY:
1.251 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.252 + * RETURNS:
1.253 + * Returns NULL if the function succeeds.
1.254 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.255 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.256 + */
1.257 +PKIX_Error *
1.258 +PKIX_CertChainChecker_IsForwardCheckingSupported(
1.259 + PKIX_CertChainChecker *checker,
1.260 + PKIX_Boolean *pForwardCheckingSupported,
1.261 + void *plContext);
1.262 +
1.263 +/*
1.264 + * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected
1.265 + * DESCRIPTION:
1.266 + *
1.267 + * Checks whether the CertChainChecker pointed to by "checker" has been
1.268 + * initialized to expect the certificates to be presented in the "forward"
1.269 + * direction and stores the Boolean result at "pForwardDirectionExpected".
1.270 + *
1.271 + * A CertChainChecker may be presented certificates in the "reverse"
1.272 + * direction (from trust anchor to target) or in the "forward" direction
1.273 + * (from target to trust anchor). All CertChainCheckers must support
1.274 + * "reverse checking", while support for "forward checking" is optional. This
1.275 + * function is used to determine in which direction the CertChainChecker
1.276 + * expects the certificates to be presented.
1.277 + *
1.278 + * PARAMETERS:
1.279 + * "checker"
1.280 + * The CertChainChecker that has been initialized to expect certificates
1.281 + * in either the "forward" or "reverse" directions. Must be non-NULL.
1.282 + * "pForwardDirectionExpected"
1.283 + * Destination of the Boolean result. Must be non-NULL.
1.284 + * "plContext"
1.285 + * Platform-specific context pointer.
1.286 + * THREAD SAFETY:
1.287 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.288 + * RETURNS:
1.289 + * Returns NULL if the function succeeds.
1.290 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.291 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.292 + */
1.293 +PKIX_Error *
1.294 +PKIX_CertChainChecker_IsForwardDirectionExpected(
1.295 + PKIX_CertChainChecker *checker,
1.296 + PKIX_Boolean *pForwardDirectionExpected,
1.297 + void *plContext);
1.298 +
1.299 +/*
1.300 + * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions
1.301 + * DESCRIPTION:
1.302 + *
1.303 + * Retrieves a pointer to a List of OIDs (each OID corresponding to a
1.304 + * certificate extension supported by the CertChainChecker pointed to by
1.305 + * "checker") and stores it at "pExtensions". All certificate extensions that
1.306 + * the CertChainChecker might possibly recognize and be able to process
1.307 + * should be included in the List of supported extensions. If "checker" does
1.308 + * not recognize or process any certificate extensions, this function stores
1.309 + * NULL at "pExtensions".
1.310 + *
1.311 + * Note that the List returned by this function is immutable.
1.312 + *
1.313 + * PARAMETERS:
1.314 + * "checker"
1.315 + * Address of CertChainChecker whose supported extension OIDs are to be
1.316 + * stored. Must be non-NULL.
1.317 + * "pExtensions"
1.318 + * Address where object pointer will be stored. Must be non-NULL.
1.319 + * "plContext"
1.320 + * Platform-specific context pointer.
1.321 + * THREAD SAFETY:
1.322 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.323 + * RETURNS:
1.324 + * Returns NULL if the function succeeds.
1.325 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.326 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.327 + */
1.328 +PKIX_Error *
1.329 +PKIX_CertChainChecker_GetSupportedExtensions(
1.330 + PKIX_CertChainChecker *checker,
1.331 + PKIX_List **pExtensions, /* list of PKIX_PL_OID */
1.332 + void *plContext);
1.333 +
1.334 +/*
1.335 + * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState
1.336 + * DESCRIPTION:
1.337 + *
1.338 + * Retrieves a pointer to a PKIX_PL_Object representing the internal state
1.339 + * (if any) of the CertChainChecker pointed to by "checker" and stores it at
1.340 + * "pCertChainCheckerState".
1.341 + *
1.342 + * PARAMETERS:
1.343 + * "checker"
1.344 + * Address of CertChainChecker whose state is to be stored.
1.345 + * Must be non-NULL.
1.346 + * "pCertChainCheckerState"
1.347 + * Address where object pointer will be stored. Must be non-NULL.
1.348 + * "plContext"
1.349 + * Platform-specific context pointer.
1.350 + * THREAD SAFETY:
1.351 + * Conditionally Thread Safe
1.352 + * (see Thread Safety Definitions in Programmer's Guide)
1.353 + * RETURNS:
1.354 + * Returns NULL if the function succeeds.
1.355 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.356 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.357 + */
1.358 +PKIX_Error *
1.359 +PKIX_CertChainChecker_GetCertChainCheckerState(
1.360 + PKIX_CertChainChecker *checker,
1.361 + PKIX_PL_Object **pCertChainCheckerState,
1.362 + void *plContext);
1.363 +
1.364 +/*
1.365 + * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState
1.366 + * DESCRIPTION:
1.367 + *
1.368 + * Sets the internal state of the CertChainChecker pointed to by "checker"
1.369 + * using the Object pointed to by "certChainCheckerState". If "checker" needs
1.370 + * a NULL internal state, "certChainCheckerState" should be set to NULL.
1.371 + *
1.372 + * PARAMETERS:
1.373 + * "checker"
1.374 + * Address of CertChainChecker whose state is to be set. Must be non-NULL.
1.375 + * "certChainCheckerState"
1.376 + * Address of Object representing internal state.
1.377 + * "plContext"
1.378 + * Platform-specific context pointer.
1.379 + * THREAD SAFETY:
1.380 + * Not Thread Safe - assumes exclusive access to "checker"
1.381 + * (see Thread Safety Definitions in Programmer's Guide)
1.382 + * RETURNS:
1.383 + * Returns NULL if the function succeeds.
1.384 + * Returns a CertChainChecker Error if the function fails in a non-fatal way.
1.385 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.386 + */
1.387 +PKIX_Error *
1.388 +PKIX_CertChainChecker_SetCertChainCheckerState(
1.389 + PKIX_CertChainChecker *checker,
1.390 + PKIX_PL_Object *certChainCheckerState,
1.391 + void *plContext);
1.392 +
1.393 +#ifdef __cplusplus
1.394 +}
1.395 +#endif
1.396 +
1.397 +#endif /* _PKIX_CHECKER_H */
