pkix.h (12181B)
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 the public API for libpkix. These are the top-level 6 * functions in the library. They perform the primary operations of this 7 * library: building and validating chains of X.509 certificates. 8 * 9 */ 10 11 #ifndef _PKIX_H 12 #define _PKIX_H 13 14 #include "pkixt.h" 15 #include "pkix_util.h" 16 #include "pkix_results.h" 17 #include "pkix_certstore.h" 18 #include "pkix_certsel.h" 19 #include "pkix_crlsel.h" 20 #include "pkix_checker.h" 21 #include "pkix_revchecker.h" 22 #include "pkix_pl_system.h" 23 #include "pkix_pl_pki.h" 24 #include "pkix_params.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /* General 31 * 32 * Please refer to the libpkix Programmer's Guide for detailed information 33 * about how to use the libpkix library. Certain key warnings and notices from 34 * that document are repeated here for emphasis. 35 * 36 * All identifiers in this file (and all public identifiers defined in 37 * libpkix) begin with "PKIX_". Private identifiers only intended for use 38 * within the library begin with "pkix_". 39 * 40 * A function returns NULL upon success, and a PKIX_Error pointer upon failure. 41 * 42 * Unless otherwise noted, for all accessor (gettor) functions that return a 43 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a 44 * shared object. Therefore, the caller should treat this shared object as 45 * read-only and should not modify this shared object. When done using the 46 * shared object, the caller should release the reference to the object by 47 * using the PKIX_PL_Object_DecRef function. 48 * 49 * While a function is executing, if its arguments (or anything referred to by 50 * its arguments) are modified, free'd, or destroyed, the function's behavior 51 * is undefined. 52 * 53 */ 54 55 /* 56 * FUNCTION: PKIX_Initialize 57 * DESCRIPTION: 58 * 59 * No PKIX_* types and functions should be used before this function is called 60 * and returns successfully. This function should only be called once. If it 61 * is called more than once, the behavior is undefined. 62 * 63 * NSS applications are expected to call NSS_Init, and need not know that 64 * NSS will call this function (with "platformInitNeeded" set to PKIX_FALSE). 65 * PKIX applications are expected instead to call this function with 66 * "platformInitNeeded" set to PKIX_TRUE. 67 * 68 * This function initializes data structures critical to the operation of 69 * libpkix. It also ensures that the API version (major.minor) desired by the 70 * caller (the "desiredMajorVersion", "minDesiredMinorVersion", and 71 * "maxDesiredMinorVersion") is compatible with the API version supported by 72 * the library. As such, the library must support the "desiredMajorVersion" 73 * of the API and must support a minor version that falls between 74 * "minDesiredMinorVersion" and "maxDesiredMinorVersion", inclusive. If 75 * compatibility exists, the function returns NULL and stores the library's 76 * actual minor version at "pActualMinorVersion" (which may be greater than 77 * "desiredMinorVersion"). If no compatibility exists, the function returns a 78 * PKIX_Error pointer. If the caller wishes to specify that the largest 79 * minor version available should be used, then maxDesiredMinorVersion should 80 * be set to the macro PKIX_MAX_MINOR_VERSION (defined in pkixt.h). 81 * 82 * PARAMETERS: 83 * "platformInitNeeded" 84 * Boolean indicating whether the platform layer initialization code 85 * has previously been run, or should be called from this function. 86 * "desiredMajorVersion" 87 * The major version of the libpkix API the application wishes to use. 88 * "minDesiredMinorVersion" 89 * The minimum minor version of the libpkix API the application wishes 90 * to use. 91 * "maxDesiredMinorVersion" 92 * The maximum minor version of the libpkix API the application wishes 93 * to use. 94 * "pActualMinorVersion" 95 * Address where PKIX_UInt32 will be stored. Must be non-NULL. 96 * "pPlContext" 97 * Address at which platform-specific context pointer is stored. Must 98 * be non-NULL. 99 * THREAD SAFETY: 100 * Not Thread Safe 101 * RETURNS: 102 * Returns NULL if the function succeeds. 103 * Returns an Initialize Error if the function fails in a non-fatal way. 104 * Returns a Fatal Error if the function fails in an unrecoverable way. 105 */ 106 PKIX_Error * 107 PKIX_Initialize( 108 PKIX_Boolean platformInitNeeded, 109 PKIX_UInt32 desiredMajorVersion, 110 PKIX_UInt32 minDesiredMinorVersion, 111 PKIX_UInt32 maxDesiredMinorVersion, 112 PKIX_UInt32 *pActualMinorVersion, 113 void **pPlContext); 114 115 /* 116 * FUNCTION: PKIX_Shutdown 117 * DESCRIPTION: 118 * 119 * This function deallocates any memory used by libpkix and shuts down any 120 * ongoing operations. This function should only be called once. If it is 121 * called more than once, the behavior is undefined. 122 * 123 * No PKIX_* types and functions should be used after this function is called 124 * and returns successfully. 125 * PARAMETERS: 126 * "plContext" - Platform-specific context pointer. 127 * THREAD SAFETY: 128 * Not Thread Safe 129 * RETURNS: 130 * Returns NULL if the function succeeds. 131 * Returns a Fatal Error if the function fails in an unrecoverable way. 132 */ 133 PKIX_Error * 134 PKIX_Shutdown(void *plContext); 135 136 /* 137 * FUNCTION: PKIX_ValidateChain 138 * DESCRIPTION: 139 * 140 * This function attempts to validate the CertChain that has been set in the 141 * ValidateParams pointed to by "params" using an RFC 3280-compliant 142 * algorithm. If successful, this function returns NULL and stores the 143 * ValidateResult at "pResult", which holds additional information, such as 144 * the policy tree and the target's public key. If unsuccessful, an Error is 145 * returned. Note: This function does not currently support non-blocking I/O. 146 * 147 * If "pVerifyTree" is non-NULL, a chain of VerifyNodes is created which 148 * tracks the results of the validation. That is, either each node in the 149 * chain has a NULL Error component, or the last node contains an Error 150 * which indicates why the validation failed. 151 * 152 * PARAMETERS: 153 * "params" 154 * Address of ValidateParams used to validate CertChain. Must be non-NULL. 155 * "pResult" 156 * Address where object pointer will be stored. Must be non-NULL. 157 * "pVerifyTree" 158 * Address where a VerifyTree is stored, if non-NULL. 159 * "plContext" 160 * Platform-specific context pointer. 161 * THREAD SAFETY: 162 * Thread Safe (See Thread Safety Definitions in Programmer's Guide) 163 * RETURNS: 164 * Returns NULL if the function succeeds. 165 * Returns a Validate Error if the function fails in a non-fatal way. 166 * Returns a Fatal Error if the function fails in an unrecoverable way. 167 */ 168 PKIX_Error * 169 PKIX_ValidateChain( 170 PKIX_ValidateParams *params, 171 PKIX_ValidateResult **pResult, 172 PKIX_VerifyNode **pVerifyTree, 173 void *plContext); 174 175 /* 176 * FUNCTION: PKIX_ValidateChain_NB 177 * DESCRIPTION: 178 * 179 * This function is the equivalent of PKIX_ValidateChain, except that it 180 * supports non-blocking I/O. When called with "pNBIOContext" pointing to NULL 181 * it initiates a new chain validation as in PKIX_ValidateChain, ignoring the 182 * value in all input variables except "params". If forced to suspend 183 * processing by a WOULDBLOCK return from some operation, such as a CertStore 184 * request, it stores the platform-dependent I/O context at "pNBIOContext" and 185 * stores other intermediate variables at "pCertIndex", "pAnchorIndex", 186 * "pCheckerIndex", "pRevChecking", and "pCheckers". 187 * 188 * When called subsequently with that non-NULL value at "pNBIOContext", it 189 * relies on those intermediate values to be untouched, and it resumes chain 190 * validation where it left off. Its behavior is undefined if any of the 191 * intermediate values was not preserved. 192 * 193 * PARAMETERS: 194 * "params" 195 * Address of ValidateParams used to validate CertChain. Must be non-NULL. 196 * "pCertIndex" 197 * The UInt32 value of the index to the Cert chain, indicating which Cert 198 * is currently being processed. 199 * "pAnchorIndex" 200 * The UInt32 value of the index to the Anchor chain, indicating which 201 * Trust Anchor is currently being processed. 202 * "pCheckerIndex" 203 * The UInt32 value of the index to the List of CertChainCheckers, 204 * indicating which Checker is currently processing. 205 * "pRevChecking" 206 * The Boolean flag indicating whether normal checking or revocation 207 * checking is occurring for the Cert indicated by "pCertIndex". 208 * "pCheckers" 209 * The address of the List of CertChainCheckers. Must be non-NULL. 210 * "pNBIOContext" 211 * The address of the platform-dependend I/O context. Must be a non-NULL 212 * pointer to a NULL value for the call to initiate chain validation. 213 * "pResult" 214 * Address where ValidateResult object pointer will be stored. Must be 215 * non-NULL. 216 * "pVerifyTree" 217 * Address where a VerifyTree is stored, if non-NULL. 218 * "plContext" 219 * Platform-specific context pointer. 220 * THREAD SAFETY: 221 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 222 * RETURNS: 223 * Returns NULL if the function succeeds. 224 * Returns a VALIDATE Error if the function fails in a non-fatal way. 225 * Returns a Fatal Error if the function fails in an unrecoverable way. 226 */PKIX_Error * 227 PKIX_ValidateChain_NB( 228 PKIX_ValidateParams *params, 229 PKIX_UInt32 *pCertIndex, 230 PKIX_UInt32 *pAnchorIndex, 231 PKIX_UInt32 *pCheckerIndex, 232 PKIX_Boolean *pRevChecking, 233 PKIX_List **pCheckers, 234 void **pNBIOContext, 235 PKIX_ValidateResult **pResult, 236 PKIX_VerifyNode **pVerifyTree, 237 void *plContext); 238 239 /* 240 * FUNCTION: PKIX_BuildChain 241 * DESCRIPTION: 242 * 243 * If called with a NULL "state", this function attempts to build and validate 244 * a CertChain according to the ProcessingParams pointed to by "params", using 245 * an RFC 3280-compliant validation algorithm. If successful, this function 246 * returns NULL and stores the BuildResult at "pResult", which holds the built 247 * CertChain, as well as additional information, such as the policy tree and 248 * the target's public key. If unsuccessful, an Error is returned. 249 * 250 * If the chain building is blocked by a CertStore using non-blocking I/O, this 251 * function stores platform-dependent non-blocking I/O context at 252 * "pNBIOContext", its state at "pState", and NULL at "pResult". The caller 253 * may be able to determine, in a platform-dependent way, when the I/O has 254 * completed. In any case, calling the function again with "pState" containing 255 * the returned value will allow the chain building to resume. 256 * 257 * If chain building is completed, either successfully or unsuccessfully, NULL 258 * is stored at "pNBIOContext". 259 * 260 * If "pVerifyTree" is non-NULL, a tree of VerifyNodes is created which 261 * tracks the results of the building. That is, each node of the tree either 262 * has a NULL Error component, or it is a leaf node and it contains an Error 263 * which indicates why the chain building could not proceed on this branch. 264 * 265 * PARAMETERS: 266 * "params" 267 * Address of ProcessingParams used to build and validate CertChain. 268 * Must be non-NULL. 269 * "pNBIOContext" 270 * Address where platform-dependent information is store if the build 271 * is suspended waiting for non-blocking I/O. Must be non-NULL. 272 * "pState" 273 * Address of BuildChain state. Must be NULL on initial call, and the 274 * value previously returned on subsequent calls. 275 * "pResult" 276 * Address where object pointer will be stored. Must be non-NULL. 277 * "pVerifyTree" 278 * Address where a VerifyTree is stored, if non-NULL. 279 * "plContext" 280 * Platform-specific context pointer. 281 * THREAD SAFETY: 282 * Thread Safe (See Thread Safety Definitions in Programmer's Guide) 283 * RETURNS: 284 * Returns NULL if the function succeeds. 285 * Returns a Build Error if the function fails in a non-fatal way. 286 * Returns a Fatal Error if the function fails in an unrecoverable way. 287 */ 288 PKIX_Error * 289 PKIX_BuildChain( 290 PKIX_ProcessingParams *params, 291 void **pNBIOContext, 292 void **pState, 293 PKIX_BuildResult **pResult, 294 PKIX_VerifyNode **pVerifyNode, 295 void *plContext); 296 297 #ifdef __cplusplus 298 } 299 #endif 300 301 #endif /* _PKIX_H */