pkix_checker.h (16802B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 /* 5 * This file defines functions associated with the PKIX_CertChainChecker type. 6 * 7 */ 8 9 #ifndef _PKIX_CHECKER_H 10 #define _PKIX_CHECKER_H 11 12 #include "pkixt.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /* General 19 * 20 * Please refer to the libpkix Programmer's Guide for detailed information 21 * about how to use the libpkix library. Certain key warnings and notices from 22 * that document are repeated here for emphasis. 23 * 24 * All identifiers in this file (and all public identifiers defined in 25 * libpkix) begin with "PKIX_". Private identifiers only intended for use 26 * within the library begin with "pkix_". 27 * 28 * A function returns NULL upon success, and a PKIX_Error pointer upon failure. 29 * 30 * Unless otherwise noted, for all accessor (gettor) functions that return a 31 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a 32 * shared object. Therefore, the caller should treat this shared object as 33 * read-only and should not modify this shared object. When done using the 34 * shared object, the caller should release the reference to the object by 35 * using the PKIX_PL_Object_DecRef function. 36 * 37 * While a function is executing, if its arguments (or anything referred to by 38 * its arguments) are modified, free'd, or destroyed, the function's behavior 39 * is undefined. 40 * 41 */ 42 43 /* PKIX_CertChainChecker 44 * 45 * PKIX_CertChainCheckers provide a standard way for the caller to insert their 46 * own custom checks to validate certificates. This may be useful in many 47 * scenarios, including when the caller wishes to validate private certificate 48 * extensions. The CheckCallback allows custom certificate processing to take 49 * place. Additionally, a CertChainChecker can optionally maintain state 50 * between successive calls to the CheckCallback. This certChainCheckerState 51 * must be an Object (although any object type), allowing it to be 52 * reference-counted and allowing it to provide the standard Object functions 53 * (Equals, Hashcode, ToString, Compare, Duplicate). If the caller wishes 54 * their CertChainChecker to be used during chain building, their 55 * certChainCheckerState object must implement an appropriate Duplicate 56 * function. The builder uses this Duplicate function when backtracking. 57 * 58 * Once the caller has created a CertChainChecker object, the caller then 59 * specifies a CertChainChecker object in a ProcessingParams object 60 * and passes the ProcessingParams object to PKIX_ValidateChain or 61 * PKIX_BuildChain, which uses the objects to call the user's callback 62 * functions as needed during the validation or building process. 63 * 64 * A CertChainChecker may be presented certificates in the "reverse" direction 65 * (from trust anchor to target) or in the "forward" direction (from target to 66 * trust anchor). All CertChainCheckers must support "reverse checking", while 67 * support for "forward checking" is optional, but recommended. If "forward 68 * checking" is not supported, building chains may be much less efficient. The 69 * PKIX_CertChainChecker_IsForwardCheckingSupported function is used to 70 * determine whether forward checking is supported, and the 71 * PKIX_CertChainChecker_IsForwardDirectionExpected function is used to 72 * determine whether the CertChainChecker has been initialized to expect the 73 * certificates to be presented in the "forward" direction. 74 */ 75 76 /* 77 * FUNCTION: PKIX_CertChainChecker_CheckCallback 78 * DESCRIPTION: 79 * 80 * This callback function checks whether the specified Cert pointed to by 81 * "cert" is valid using "checker's" internal certChainCheckerState (if any) 82 * and removes the critical extensions that it processes (if any) from the 83 * List of OIDs (possibly empty) pointed to by "unresolvedCriticalExtensions". 84 * If the checker finds that the certificate is not valid, an Error pointer is 85 * returned. 86 * 87 * If the checker uses non-blocking I/O, the address of a platform-dependent 88 * non-blocking I/O context ("nbioContext") will be stored at "pNBIOContext", 89 * which the caller may use, in a platform-dependent way, to wait, poll, or 90 * otherwise determine when to try again. If the checker does not use 91 * non-blocking I/O, NULL will always be stored at "pNBIOContext". If a non-NULL 92 * value was stored, on a subsequent call the checker will attempt to complete 93 * the pending I/O and, if successful, NULL will be stored at "pNBIOContext". 94 * 95 * PARAMETERS: 96 * "checker" 97 * Address of CertChainChecker whose certChainCheckerState and 98 * CheckCallback logic is to be used. Must be non-NULL. 99 * "cert" 100 * Address of Cert that is to be validated using "checker". 101 * Must be non-NULL. 102 * "unresolvedCriticalExtensions" 103 * Address of List of OIDs that represents the critical certificate 104 * extensions that have yet to be resolved. This parameter may be 105 * modified during the function call. Must be non-NULL. 106 * "pNBIOContext" 107 * Address at which is stored a platform-dependent structure indicating 108 * whether checking was suspended for non-blocking I/O. Must be non-NULL. 109 * "plContext" 110 * Platform-specific context pointer. 111 * THREAD SAFETY: 112 * Thread Safe 113 * 114 * Multiple threads must be able to safely call this function without 115 * worrying about conflicts, even if they're operating on the same object. 116 * RETURNS: 117 * Returns NULL if the function succeeds. 118 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 119 * Returns a Fatal Error if the function fails in an unrecoverable way. 120 */ 121 typedef PKIX_Error * 122 (*PKIX_CertChainChecker_CheckCallback)( 123 PKIX_CertChainChecker *checker, 124 PKIX_PL_Cert *cert, 125 PKIX_List *unresolvedCriticalExtensions, /* list of PKIX_PL_OID */ 126 void **pNBIOContext, 127 void *plContext); 128 129 /* 130 * FUNCTION: PKIX_CertChainChecker_Create 131 * DESCRIPTION: 132 * 133 * Creates a new CertChainChecker and stores it at "pChecker". The new 134 * CertChainChecker uses the CheckCallback pointed to by "callback" as its 135 * callback function. It uses the Object pointed to by "initialState" (if 136 * any) as its initial state. As noted above, the initial state Object must 137 * provide a custom implementation of PKIX_PL_Object_Duplicate if the 138 * CertChainChecker is to be used during certificate chain building. 139 * 140 * A CertChainChecker may be presented certificates in the "reverse" 141 * direction (from trust anchor to target) or in the "forward" direction 142 * (from target to trust anchor). All CertChainCheckers must support 143 * "reverse checking", while support for "forward checking" is optional. The 144 * CertChainChecker is initialized with two Boolean flags that deal with this 145 * distinction: "forwardCheckingSupported" and "forwardDirectionExpected". 146 * If the "forwardCheckingSupported" Boolean flag is TRUE, it indicates that 147 * this CertChainChecker is capable of checking certificates in the "forward" 148 * direction (as well as the "reverse" direction, which all CertChainCheckers 149 * MUST support). The "forwardDirectionExpected" Boolean flag indicates in 150 * which direction the CertChainChecker should expect the certificates to be 151 * presented. This is particularly useful for CertChainCheckers that are 152 * capable of checking in either the "forward" direction or the "reverse" 153 * direction, but have different processing steps depending on the direction. 154 * 155 * The CertChainChecker also uses the List of OIDs pointed to by "extensions" 156 * as the supported certificate extensions. All certificate extensions that 157 * the CertChainChecker might possibly recognize and be able to process 158 * should be included in the List of supported extensions. If "checker" does 159 * not recognize or process any certificate extensions, "extensions" should 160 * be set to NULL. 161 * 162 * PARAMETERS: 163 * "callback" 164 * The CheckCallback function to be used. Must be non-NULL. 165 * "forwardCheckingSupported" 166 * A Boolean value indicating whether or not this CertChainChecker is 167 * capable of checking certificates in the "forward" direction. 168 * "forwardDirectionExpected" 169 * A Boolean value indicating whether or not this CertChainChecker should 170 * be used to check in the "forward" direction. 171 * "extensions" 172 * Address of List of OIDs representing the supported extensions. 173 * "initialState" 174 * Address of Object representing the CertChainChecker's initial state 175 * (if any). 176 * "pChecker" 177 * Address where object pointer will be stored. Must be non-NULL. 178 * "plContext" 179 * Platform-specific context pointer. 180 * THREAD SAFETY: 181 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 182 * RETURNS: 183 * Returns NULL if the function succeeds. 184 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 185 * Returns a Fatal Error if the function fails in an unrecoverable way. 186 */ 187 PKIX_Error * 188 PKIX_CertChainChecker_Create( 189 PKIX_CertChainChecker_CheckCallback callback, 190 PKIX_Boolean forwardCheckingSupported, 191 PKIX_Boolean forwardDirectionExpected, 192 PKIX_List *extensions, /* list of PKIX_PL_OID */ 193 PKIX_PL_Object *initialState, 194 PKIX_CertChainChecker **pChecker, 195 void *plContext); 196 197 /* 198 * FUNCTION: PKIX_CertChainChecker_GetCheckCallback 199 * DESCRIPTION: 200 * 201 * Retrieves a pointer to "checker's" Check callback function and puts it in 202 * "pCallback". 203 * 204 * PARAMETERS: 205 * "checker" 206 * The CertChainChecker whose Check callback is desired. Must be non-NULL. 207 * "pCallback" 208 * Address where Check callback function pointer will be stored. 209 * Must be non-NULL. 210 * "plContext" 211 * Platform-specific context pointer. 212 * THREAD SAFETY: 213 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 214 * RETURNS: 215 * Returns NULL if the function succeeds. 216 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 217 * Returns a Fatal Error if the function fails in an unrecoverable way. 218 */ 219 PKIX_Error * 220 PKIX_CertChainChecker_GetCheckCallback( 221 PKIX_CertChainChecker *checker, 222 PKIX_CertChainChecker_CheckCallback *pCallback, 223 void *plContext); 224 225 /* 226 * FUNCTION: PKIX_CertChainChecker_IsForwardCheckingSupported 227 * DESCRIPTION: 228 * 229 * Checks whether forward checking is supported by the CertChainChecker 230 * pointed to by "checker" and stores the Boolean result at 231 * "pForwardCheckingSupported". 232 * 233 * A CertChainChecker may be presented certificates in the "reverse" 234 * direction (from trust anchor to target) or in the "forward" direction 235 * (from target to trust anchor). All CertChainCheckers must support 236 * "reverse checking", while support for "forward checking" is optional. This 237 * function is used to determine whether forward checking is supported. 238 * 239 * PARAMETERS: 240 * "checker" 241 * The CertChainChecker whose ability to validate certificates in the 242 * "forward" direction is to be checked. Must be non-NULL. 243 * "pForwardCheckingSupported" 244 * Destination of the Boolean result. Must be non-NULL. 245 * "plContext" 246 * Platform-specific context pointer. 247 * THREAD SAFETY: 248 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 249 * RETURNS: 250 * Returns NULL if the function succeeds. 251 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 252 * Returns a Fatal Error if the function fails in an unrecoverable way. 253 */ 254 PKIX_Error * 255 PKIX_CertChainChecker_IsForwardCheckingSupported( 256 PKIX_CertChainChecker *checker, 257 PKIX_Boolean *pForwardCheckingSupported, 258 void *plContext); 259 260 /* 261 * FUNCTION: PKIX_CertChainChecker_IsForwardDirectionExpected 262 * DESCRIPTION: 263 * 264 * Checks whether the CertChainChecker pointed to by "checker" has been 265 * initialized to expect the certificates to be presented in the "forward" 266 * direction and stores the Boolean result at "pForwardDirectionExpected". 267 * 268 * A CertChainChecker may be presented certificates in the "reverse" 269 * direction (from trust anchor to target) or in the "forward" direction 270 * (from target to trust anchor). All CertChainCheckers must support 271 * "reverse checking", while support for "forward checking" is optional. This 272 * function is used to determine in which direction the CertChainChecker 273 * expects the certificates to be presented. 274 * 275 * PARAMETERS: 276 * "checker" 277 * The CertChainChecker that has been initialized to expect certificates 278 * in either the "forward" or "reverse" directions. Must be non-NULL. 279 * "pForwardDirectionExpected" 280 * Destination of the Boolean result. Must be non-NULL. 281 * "plContext" 282 * Platform-specific context pointer. 283 * THREAD SAFETY: 284 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 285 * RETURNS: 286 * Returns NULL if the function succeeds. 287 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 288 * Returns a Fatal Error if the function fails in an unrecoverable way. 289 */ 290 PKIX_Error * 291 PKIX_CertChainChecker_IsForwardDirectionExpected( 292 PKIX_CertChainChecker *checker, 293 PKIX_Boolean *pForwardDirectionExpected, 294 void *plContext); 295 296 /* 297 * FUNCTION: PKIX_CertChainChecker_GetSupportedExtensions 298 * DESCRIPTION: 299 * 300 * Retrieves a pointer to a List of OIDs (each OID corresponding to a 301 * certificate extension supported by the CertChainChecker pointed to by 302 * "checker") and stores it at "pExtensions". All certificate extensions that 303 * the CertChainChecker might possibly recognize and be able to process 304 * should be included in the List of supported extensions. If "checker" does 305 * not recognize or process any certificate extensions, this function stores 306 * NULL at "pExtensions". 307 * 308 * Note that the List returned by this function is immutable. 309 * 310 * PARAMETERS: 311 * "checker" 312 * Address of CertChainChecker whose supported extension OIDs are to be 313 * stored. Must be non-NULL. 314 * "pExtensions" 315 * Address where object pointer will be stored. Must be non-NULL. 316 * "plContext" 317 * Platform-specific context pointer. 318 * THREAD SAFETY: 319 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 320 * RETURNS: 321 * Returns NULL if the function succeeds. 322 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 323 * Returns a Fatal Error if the function fails in an unrecoverable way. 324 */ 325 PKIX_Error * 326 PKIX_CertChainChecker_GetSupportedExtensions( 327 PKIX_CertChainChecker *checker, 328 PKIX_List **pExtensions, /* list of PKIX_PL_OID */ 329 void *plContext); 330 331 /* 332 * FUNCTION: PKIX_CertChainChecker_GetCertChainCheckerState 333 * DESCRIPTION: 334 * 335 * Retrieves a pointer to a PKIX_PL_Object representing the internal state 336 * (if any) of the CertChainChecker pointed to by "checker" and stores it at 337 * "pCertChainCheckerState". 338 * 339 * PARAMETERS: 340 * "checker" 341 * Address of CertChainChecker whose state is to be stored. 342 * Must be non-NULL. 343 * "pCertChainCheckerState" 344 * Address where object pointer will be stored. Must be non-NULL. 345 * "plContext" 346 * Platform-specific context pointer. 347 * THREAD SAFETY: 348 * Conditionally Thread Safe 349 * (see Thread Safety Definitions in Programmer's Guide) 350 * RETURNS: 351 * Returns NULL if the function succeeds. 352 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 353 * Returns a Fatal Error if the function fails in an unrecoverable way. 354 */ 355 PKIX_Error * 356 PKIX_CertChainChecker_GetCertChainCheckerState( 357 PKIX_CertChainChecker *checker, 358 PKIX_PL_Object **pCertChainCheckerState, 359 void *plContext); 360 361 /* 362 * FUNCTION: PKIX_CertChainChecker_SetCertChainCheckerState 363 * DESCRIPTION: 364 * 365 * Sets the internal state of the CertChainChecker pointed to by "checker" 366 * using the Object pointed to by "certChainCheckerState". If "checker" needs 367 * a NULL internal state, "certChainCheckerState" should be set to NULL. 368 * 369 * PARAMETERS: 370 * "checker" 371 * Address of CertChainChecker whose state is to be set. Must be non-NULL. 372 * "certChainCheckerState" 373 * Address of Object representing internal state. 374 * "plContext" 375 * Platform-specific context pointer. 376 * THREAD SAFETY: 377 * Not Thread Safe - assumes exclusive access to "checker" 378 * (see Thread Safety Definitions in Programmer's Guide) 379 * RETURNS: 380 * Returns NULL if the function succeeds. 381 * Returns a CertChainChecker Error if the function fails in a non-fatal way. 382 * Returns a Fatal Error if the function fails in an unrecoverable way. 383 */ 384 PKIX_Error * 385 PKIX_CertChainChecker_SetCertChainCheckerState( 386 PKIX_CertChainChecker *checker, 387 PKIX_PL_Object *certChainCheckerState, 388 void *plContext); 389 390 #ifdef __cplusplus 391 } 392 #endif 393 394 #endif /* _PKIX_CHECKER_H */