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 CertStore types. 6 * 7 */ 8 9 10 #ifndef _PKIX_SAMPLEMODULES_H 11 #define _PKIX_SAMPLEMODULES_H 12 13 #include "pkix_pl_common.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /* General 20 * 21 * Please refer to the libpkix Programmer's Guide for detailed information 22 * about how to use the libpkix library. Certain key warnings and notices from 23 * that document are repeated here for emphasis. 24 * 25 * All identifiers in this file (and all public identifiers defined in 26 * libpkix) begin with "PKIX_". Private identifiers only intended for use 27 * within the library begin with "pkix_". 28 * 29 * A function returns NULL upon success, and a PKIX_Error pointer upon failure. 30 * 31 * Unless otherwise noted, for all accessor (gettor) functions that return a 32 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a 33 * shared object. Therefore, the caller should treat this shared object as 34 * read-only and should not modify this shared object. When done using the 35 * shared object, the caller should release the reference to the object by 36 * using the PKIX_PL_Object_DecRef function. 37 * 38 * While a function is executing, if its arguments (or anything referred to by 39 * its arguments) are modified, free'd, or destroyed, the function's behavior 40 * is undefined. 41 * 42 */ 43 44 /* PKIX_PL_CollectionCertStore 45 * 46 * A PKIX_CollectionCertStore provides an example for showing how to retrieve 47 * certificates and CRLs from a repository, such as a directory in the system. 48 * It is expected the directory is an absolute directory which contains CRL 49 * and Cert data files. CRL files are expected to have the suffix of .crl 50 * and Cert files are expected to have the suffix of .crt . 51 * 52 * Once the caller has created the CollectionCertStoreContext object, the caller 53 * then can call pkix_pl_CollectionCertStore_GetCert or 54 * pkix_pl_CollectionCertStore_GetCRL to obtain Lists of PKIX_PL_Cert or 55 * PKIX_PL_CRL objects, respectively. 56 */ 57 58 /* 59 * FUNCTION: PKIX_PL_CollectionCertStore_Create 60 * DESCRIPTION: 61 * 62 * Creates a new CollectionCertStore and returns it at 63 * "pColCertStore". 64 * 65 * PARAMETERS: 66 * "storeDir" 67 * The absolute path where *.crl files are located. 68 * "pColCertStoreContext" 69 * Address where object pointer will be stored. Must be non-NULL. 70 * "plContext" 71 * Platform-specific context pointer. 72 * THREAD SAFETY: 73 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 74 * RETURNS: 75 * Returns NULL if the function succeeds. 76 * Returns a CollectionCertStoreContext Error if the function fails in 77 * a non-fatal way. 78 * Returns a Fatal Error if the function fails in an unrecoverable way. 79 */ 80 PKIX_Error * 81 PKIX_PL_CollectionCertStore_Create( 82 PKIX_PL_String *storeDir, 83 PKIX_CertStore **pCertStore, 84 void *plContext); 85 86 /* PKIX_PL_PK11CertStore 87 * 88 * A PKIX_PL_PK11CertStore retrieves certificates and CRLs from a PKCS11 89 * database. The directory that contains the cert8.db, key3.db, and secmod.db 90 * files that comprise a PKCS11 database are specified in NSS initialization. 91 * 92 * Once the caller has created the Pk11CertStore object, the caller can call 93 * pkix_pl_Pk11CertStore_GetCert or pkix_pl_Pk11CertStore_GetCert to obtain 94 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively. 95 */ 96 97 /* 98 * FUNCTION: PKIX_PL_Pk11CertStore_Create 99 * DESCRIPTION: 100 * 101 * Creates a new Pk11CertStore and returns it at "pPk11CertStore". 102 * 103 * PARAMETERS: 104 * "pPk11CertStore" 105 * Address where object pointer will be stored. Must be non-NULL. 106 * "plContext" 107 * Platform-specific context pointer. 108 * THREAD SAFETY: 109 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 110 * RETURNS: 111 * Returns NULL if the function succeeds. 112 * Returns a CertStore Error if the function fails in a non-fatal way. 113 * Returns a Fatal Error if the function fails in an unrecoverable way. 114 */ 115 PKIX_Error * 116 PKIX_PL_Pk11CertStore_Create( 117 PKIX_CertStore **pPk11CertStore, 118 void *plContext); 119 120 #ifndef NSS_PKIX_NO_LDAP 121 /* PKIX_PL_LdapCertStore 122 * 123 * A PKIX_PL_LdapCertStore retrieves certificates and CRLs from an LDAP server 124 * over a socket connection. It used the LDAP protocol as described in RFC1777. 125 * 126 * Once the caller has created the LdapCertStore object, the caller can call 127 * pkix_pl_LdapCertStore_GetCert or pkix_pl_LdapCertStore_GetCert to obtain 128 * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively. 129 */ 130 131 /* 132 * FUNCTION: PKIX_PL_LdapDefaultClient_Create 133 * DESCRIPTION: 134 * 135 * Creates an LdapDefaultClient using the PRNetAddr poined to by "sockaddr", 136 * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI"; 137 * and stores the address of the default LdapClient at "pClient". 138 * 139 * At the time of this version, there are unresolved questions about the LDAP 140 * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not 141 * clear whether they are appropriate to this application. We have tested only 142 * using servers that do not expect authentication, and that reject BIND 143 * messages. It is not clear what values might be appropriate for the bindname 144 * and authentication fields, which are currently implemented as char strings 145 * supplied by the caller. (If this changes, the API and possibly the templates 146 * will have to change.) Therefore the Client_Create API contains a BindAPI 147 * structure, a union, which will have to be revised and extended when this 148 * area of the protocol is better understood. 149 * 150 * PARAMETERS: 151 * "sockaddr" 152 * Address of the PRNetAddr to be used for the socket connection. Must be 153 * non-NULL. 154 * "timeout" 155 * The PRIntervalTime value to be used as a timeout value in socket calls; 156 * a zero value indicates non-blocking I/O is to be used. 157 * "bindAPI" 158 * The address of a BindAPI to be used if a BIND message is required. If 159 * this argument is NULL, no Bind (or Unbind) will be sent. 160 * "pClient" 161 * Address where object pointer will be stored. Must be non-NULL. 162 * "plContext" 163 * Platform-specific context pointer. 164 * THREAD SAFETY: 165 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 166 * RETURNS: 167 * Returns NULL if the function succeeds. 168 * Returns a CertStore Error if the function fails in a non-fatal way. 169 * Returns a Fatal Error if the function fails in an unrecoverable way. 170 */ 171 PKIX_Error * 172 PKIX_PL_LdapDefaultClient_Create( 173 PRNetAddr *sockaddr, 174 PRIntervalTime timeout, 175 LDAPBindAPI *bindAPI, 176 PKIX_PL_LdapDefaultClient **pClient, 177 void *plContext); 178 179 /* 180 * FUNCTION: PKIX_PL_LdapDefaultClient_CreateByName 181 * DESCRIPTION: 182 * 183 * Creates an LdapDefaultClient using the hostname poined to by "hostname", 184 * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI"; 185 * and stores the address of the default LdapClient at "pClient". 186 * 187 * At the time of this version, there are unresolved questions about the LDAP 188 * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not 189 * clear whether they are appropriate to this application. We have tested only 190 * using servers that do not expect authentication, and that reject BIND 191 * messages. It is not clear what values might be appropriate for the bindname 192 * and authentication fields, which are currently implemented as char strings 193 * supplied by the caller. (If this changes, the API and possibly the templates 194 * will have to change.) Therefore the Client_Create API contains a BindAPI 195 * structure, a union, which will have to be revised and extended when this 196 * area of the protocol is better understood. 197 * 198 * PARAMETERS: 199 * "hostname" 200 * Address of the hostname to be used for the socket connection. Must be 201 * non-NULL. 202 * "timeout" 203 * The PRIntervalTime value to be used as a timeout value in socket calls; 204 * a zero value indicates non-blocking I/O is to be used. 205 * "bindAPI" 206 * The address of a BindAPI to be used if a BIND message is required. If 207 * this argument is NULL, no Bind (or Unbind) will be sent. 208 * "pClient" 209 * Address where object pointer will be stored. 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 CertStore 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_PL_LdapDefaultClient_CreateByName( 221 char *hostname, 222 PRIntervalTime timeout, 223 LDAPBindAPI *bindAPI, 224 PKIX_PL_LdapDefaultClient **pClient, 225 void *plContext); 226 227 /* 228 * FUNCTION: PKIX_PL_LdapCertStore_Create 229 * DESCRIPTION: 230 * 231 * Creates a new LdapCertStore using the LdapClient pointed to by "client", 232 * and stores the address of the CertStore at "pCertStore". 233 * 234 * PARAMETERS: 235 * "client" 236 * Address of the LdapClient to be used. Must be non-NULL. 237 * "pCertStore" 238 * Address where object pointer will be stored. Must be non-NULL. 239 * "plContext" 240 * Platform-specific context pointer. 241 * THREAD SAFETY: 242 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 243 * RETURNS: 244 * Returns NULL if the function succeeds. 245 * Returns a CertStore Error if the function fails in a non-fatal way. 246 * Returns a Fatal Error if the function fails in an unrecoverable way. 247 */ 248 PKIX_Error * 249 PKIX_PL_LdapCertStore_Create( 250 PKIX_PL_LdapClient *client, 251 PKIX_CertStore **pCertStore, 252 void *plContext); 253 #endif /* !NSS_PKIX_NO_LDAP */ 254 255 /* PKIX_PL_NssContext 256 * 257 * A PKIX_PL_NssContext provides an example showing how the "plContext" 258 * argument, that is part of every libpkix function call, can be used. 259 * The "plContext" is the Portability Layer Context, which can be used 260 * to communicate layer-specific information from the application to the 261 * underlying Portability Layer (while bypassing the Portable Code, which 262 * blindly passes the plContext on to every function call). 263 * 264 * In this case, NSS serves as both the application and the Portability Layer. 265 * We define an NSS-specific structure, which includes an arena and a number 266 * of SECCertificateUsage bit flags encoded as a PKIX_UInt32. A third argument, 267 * wincx, is used on Windows platforms for PKCS11 access, and should be set to 268 * NULL for other platforms. 269 * Before calling any of the libpkix functions, the caller should create the NSS 270 * context, by calling PKIX_PL_NssContext_Create, and provide that NSS context 271 * as the "plContext" argument in every libpkix function call the caller makes. 272 * When the caller is finished using the NSS context (usually just after he 273 * calls PKIX_Shutdown), the caller should call PKIX_PL_NssContext_Destroy to 274 * free the NSS context structure. 275 */ 276 277 /* 278 * FUNCTION: PKIX_PL_NssContext_Create 279 * DESCRIPTION: 280 * 281 * Creates a new NssContext using the certificate usage(s) specified by 282 * "certUsage" and stores it at "pNssContext". This function also internally 283 * creates an arena and stores it as part of the NssContext structure. Unlike 284 * most other libpkix API functions, this function does not take a "plContext" 285 * parameter. 286 * 287 * PARAMETERS: 288 * "certUsage" 289 * The desired SECCertificateUsage(s). 290 * "useNssArena" 291 * Boolean flag indicates NSS Arena is used for memory allocation. 292 * "wincx" 293 * A Windows-dependent pointer for PKCS11 token handling. 294 * "pNssContext" 295 * Address where object pointer will be stored. Must be non-NULL. 296 * THREAD SAFETY: 297 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 298 * RETURNS: 299 * Returns NULL if the function succeeds. 300 * Returns a Context Error if the function fails in a non-fatal way. 301 * Returns a Fatal Error if the function fails in an unrecoverable way. 302 */ 303 PKIX_Error * 304 PKIX_PL_NssContext_Create( 305 PKIX_UInt32 certificateUsage, 306 PKIX_Boolean useNssArena, 307 void *wincx, 308 void **pNssContext); 309 310 /* 311 * FUNCTION: PKIX_PL_NssContext_Destroy 312 * DESCRIPTION: 313 * 314 * Frees the structure pointed to by "nssContext" along with any of its 315 * associated memory. Unlike most other libpkix API functions, this function 316 * does not take a "plContext" parameter. 317 * 318 * PARAMETERS: 319 * "nssContext" 320 * Address of NssContext to be destroyed. Must be non-NULL. 321 * THREAD SAFETY: 322 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 323 * RETURNS: 324 * Returns NULL if the function succeeds. 325 * Returns a Context Error if the function fails in a non-fatal way. 326 * Returns a Fatal Error if the function fails in an unrecoverable way. 327 */ 328 PKIX_Error * 329 PKIX_PL_NssContext_Destroy( 330 void *nssContext); 331 332 /* 333 * FUNCTION: PKIX_PL_NssContext_SetTimeout 334 * DESCRIPTION: 335 * 336 * Sets IO timeout for network operations like OCSP response and cert 337 * fetching. 338 * 339 * PARAMETERS: 340 * "nssContext" 341 * Address of NssContext to be destroyed. Must be non-NULL. 342 * THREAD SAFETY: 343 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 344 * RETURNS: 345 * Returns NULL if the function succeeds. 346 * Returns a Context Error if the function fails in a non-fatal way. 347 * Returns a Fatal Error if the function fails in an unrecoverable way. 348 */ 349 PKIX_Error * 350 PKIX_PL_NssContext_SetTimeout(PKIX_UInt32 timeout, PKIX_PL_NssContext *nssContext); 351 352 /* 353 * FUNCTION: PKIX_PL_NssContext_SetMaxResponseLen 354 * DESCRIPTION: 355 * 356 * Sets maximum responce length allowed during network IO operations. 357 * 358 * PARAMETERS: 359 * "nssContext" 360 * Address of NssContext to be destroyed. Must be non-NULL. 361 * THREAD SAFETY: 362 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 363 * RETURNS: 364 * Returns NULL if the function succeeds. 365 * Returns a Context Error if the function fails in a non-fatal way. 366 * Returns a Fatal Error if the function fails in an unrecoverable way. 367 */ 368 PKIX_Error * 369 PKIX_PL_NssContext_SetMaxResponseLen(PKIX_UInt32 len, PKIX_PL_NssContext *nssContext); 370 371 /* 372 * FUNCTION: PKIX_PL_NssContext_SetCrlReloadDelay 373 * DESCRIPTION: 374 * 375 * Sets user defined timeout between attempts to load crl using 376 * CRLDP. 377 * 378 * PARAMETERS: 379 * "delaySeconds" 380 * Reload delay in seconds. 381 * "nssContext" 382 * Address of NssContext to be destroyed. Must be non-NULL. 383 * THREAD SAFETY: 384 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 385 * RETURNS: 386 * Returns NULL if the function succeeds. 387 * Returns a Context Error if the function fails in a non-fatal way. 388 * Returns a Fatal Error if the function fails in an unrecoverable way. 389 */ 390 PKIX_Error * 391 PKIX_PL_NssContext_SetCrlReloadDelay(PKIX_UInt32 delaySeconds, 392 PKIX_PL_NssContext *nssContext); 393 394 /* 395 * FUNCTION: PKIX_PL_NssContext_SetBadDerCrlReloadDelay 396 * DESCRIPTION: 397 * 398 * Sets user defined timeout between attempts to load crls 399 * that failed to decode. 400 * 401 * PARAMETERS: 402 * "delaySeconds" 403 * Reload delay in seconds. 404 * "nssContext" 405 * Address of NssContext to be destroyed. Must be non-NULL. 406 * THREAD SAFETY: 407 * Thread Safe (see Thread Safety Definitions in Programmer's Guide) 408 * RETURNS: 409 * Returns NULL if the function succeeds. 410 * Returns a Context Error if the function fails in a non-fatal way. 411 * Returns a Fatal Error if the function fails in an unrecoverable way. 412 */ 413 PKIX_Error * 414 PKIX_PL_NssContext_SetBadDerCrlReloadDelay(PKIX_UInt32 delaySeconds, 415 PKIX_PL_NssContext *nssContext); 416 #ifdef __cplusplus 417 } 418 #endif 419 420 #endif /* _PKIX_SAMPLEMODULES_H */ 421