1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/libpkix/include/pkix_sample_modules.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,420 @@
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 CertStore types.
1.9 + *
1.10 + */
1.11 +
1.12 +
1.13 +#ifndef _PKIX_SAMPLEMODULES_H
1.14 +#define _PKIX_SAMPLEMODULES_H
1.15 +
1.16 +#include "pkix_pl_common.h"
1.17 +
1.18 +#ifdef __cplusplus
1.19 +extern "C" {
1.20 +#endif
1.21 +
1.22 +/* General
1.23 + *
1.24 + * Please refer to the libpkix Programmer's Guide for detailed information
1.25 + * about how to use the libpkix library. Certain key warnings and notices from
1.26 + * that document are repeated here for emphasis.
1.27 + *
1.28 + * All identifiers in this file (and all public identifiers defined in
1.29 + * libpkix) begin with "PKIX_". Private identifiers only intended for use
1.30 + * within the library begin with "pkix_".
1.31 + *
1.32 + * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
1.33 + *
1.34 + * Unless otherwise noted, for all accessor (gettor) functions that return a
1.35 + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
1.36 + * shared object. Therefore, the caller should treat this shared object as
1.37 + * read-only and should not modify this shared object. When done using the
1.38 + * shared object, the caller should release the reference to the object by
1.39 + * using the PKIX_PL_Object_DecRef function.
1.40 + *
1.41 + * While a function is executing, if its arguments (or anything referred to by
1.42 + * its arguments) are modified, free'd, or destroyed, the function's behavior
1.43 + * is undefined.
1.44 + *
1.45 + */
1.46 +
1.47 +/* PKIX_PL_CollectionCertStore
1.48 + *
1.49 + * A PKIX_CollectionCertStore provides an example for showing how to retrieve
1.50 + * certificates and CRLs from a repository, such as a directory in the system.
1.51 + * It is expected the directory is an absolute directory which contains CRL
1.52 + * and Cert data files. CRL files are expected to have the suffix of .crl
1.53 + * and Cert files are expected to have the suffix of .crt .
1.54 + *
1.55 + * Once the caller has created the CollectionCertStoreContext object, the caller
1.56 + * then can call pkix_pl_CollectionCertStore_GetCert or
1.57 + * pkix_pl_CollectionCertStore_GetCRL to obtain Lists of PKIX_PL_Cert or
1.58 + * PKIX_PL_CRL objects, respectively.
1.59 + */
1.60 +
1.61 +/*
1.62 + * FUNCTION: PKIX_PL_CollectionCertStore_Create
1.63 + * DESCRIPTION:
1.64 + *
1.65 + * Creates a new CollectionCertStore and returns it at
1.66 + * "pColCertStore".
1.67 + *
1.68 + * PARAMETERS:
1.69 + * "storeDir"
1.70 + * The absolute path where *.crl files are located.
1.71 + * "pColCertStoreContext"
1.72 + * Address where object pointer will be stored. Must be non-NULL.
1.73 + * "plContext"
1.74 + * Platform-specific context pointer.
1.75 + * THREAD SAFETY:
1.76 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.77 + * RETURNS:
1.78 + * Returns NULL if the function succeeds.
1.79 + * Returns a CollectionCertStoreContext Error if the function fails in
1.80 + * a non-fatal way.
1.81 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.82 + */
1.83 +PKIX_Error *
1.84 +PKIX_PL_CollectionCertStore_Create(
1.85 + PKIX_PL_String *storeDir,
1.86 + PKIX_CertStore **pCertStore,
1.87 + void *plContext);
1.88 +
1.89 +/* PKIX_PL_PK11CertStore
1.90 + *
1.91 + * A PKIX_PL_PK11CertStore retrieves certificates and CRLs from a PKCS11
1.92 + * database. The directory that contains the cert8.db, key3.db, and secmod.db
1.93 + * files that comprise a PKCS11 database are specified in NSS initialization.
1.94 + *
1.95 + * Once the caller has created the Pk11CertStore object, the caller can call
1.96 + * pkix_pl_Pk11CertStore_GetCert or pkix_pl_Pk11CertStore_GetCert to obtain
1.97 + * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
1.98 + */
1.99 +
1.100 +/*
1.101 + * FUNCTION: PKIX_PL_Pk11CertStore_Create
1.102 + * DESCRIPTION:
1.103 + *
1.104 + * Creates a new Pk11CertStore and returns it at "pPk11CertStore".
1.105 + *
1.106 + * PARAMETERS:
1.107 + * "pPk11CertStore"
1.108 + * Address where object pointer will be stored. Must be non-NULL.
1.109 + * "plContext"
1.110 + * Platform-specific context pointer.
1.111 + * THREAD SAFETY:
1.112 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.113 + * RETURNS:
1.114 + * Returns NULL if the function succeeds.
1.115 + * Returns a CertStore Error if the function fails in a non-fatal way.
1.116 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.117 + */
1.118 +PKIX_Error *
1.119 +PKIX_PL_Pk11CertStore_Create(
1.120 + PKIX_CertStore **pPk11CertStore,
1.121 + void *plContext);
1.122 +
1.123 +#ifndef NSS_PKIX_NO_LDAP
1.124 +/* PKIX_PL_LdapCertStore
1.125 + *
1.126 + * A PKIX_PL_LdapCertStore retrieves certificates and CRLs from an LDAP server
1.127 + * over a socket connection. It used the LDAP protocol as described in RFC1777.
1.128 + *
1.129 + * Once the caller has created the LdapCertStore object, the caller can call
1.130 + * pkix_pl_LdapCertStore_GetCert or pkix_pl_LdapCertStore_GetCert to obtain
1.131 + * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively.
1.132 + */
1.133 +
1.134 +/*
1.135 + * FUNCTION: PKIX_PL_LdapDefaultClient_Create
1.136 + * DESCRIPTION:
1.137 + *
1.138 + * Creates an LdapDefaultClient using the PRNetAddr poined to by "sockaddr",
1.139 + * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
1.140 + * and stores the address of the default LdapClient at "pClient".
1.141 + *
1.142 + * At the time of this version, there are unresolved questions about the LDAP
1.143 + * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
1.144 + * clear whether they are appropriate to this application. We have tested only
1.145 + * using servers that do not expect authentication, and that reject BIND
1.146 + * messages. It is not clear what values might be appropriate for the bindname
1.147 + * and authentication fields, which are currently implemented as char strings
1.148 + * supplied by the caller. (If this changes, the API and possibly the templates
1.149 + * will have to change.) Therefore the Client_Create API contains a BindAPI
1.150 + * structure, a union, which will have to be revised and extended when this
1.151 + * area of the protocol is better understood.
1.152 + *
1.153 + * PARAMETERS:
1.154 + * "sockaddr"
1.155 + * Address of the PRNetAddr to be used for the socket connection. Must be
1.156 + * non-NULL.
1.157 + * "timeout"
1.158 + * The PRIntervalTime value to be used as a timeout value in socket calls;
1.159 + * a zero value indicates non-blocking I/O is to be used.
1.160 + * "bindAPI"
1.161 + * The address of a BindAPI to be used if a BIND message is required. If
1.162 + * this argument is NULL, no Bind (or Unbind) will be sent.
1.163 + * "pClient"
1.164 + * Address where object pointer will be stored. Must be non-NULL.
1.165 + * "plContext"
1.166 + * Platform-specific context pointer.
1.167 + * THREAD SAFETY:
1.168 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.169 + * RETURNS:
1.170 + * Returns NULL if the function succeeds.
1.171 + * Returns a CertStore Error if the function fails in a non-fatal way.
1.172 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.173 + */
1.174 +PKIX_Error *
1.175 +PKIX_PL_LdapDefaultClient_Create(
1.176 + PRNetAddr *sockaddr,
1.177 + PRIntervalTime timeout,
1.178 + LDAPBindAPI *bindAPI,
1.179 + PKIX_PL_LdapDefaultClient **pClient,
1.180 + void *plContext);
1.181 +
1.182 +/*
1.183 + * FUNCTION: PKIX_PL_LdapDefaultClient_CreateByName
1.184 + * DESCRIPTION:
1.185 + *
1.186 + * Creates an LdapDefaultClient using the hostname poined to by "hostname",
1.187 + * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI";
1.188 + * and stores the address of the default LdapClient at "pClient".
1.189 + *
1.190 + * At the time of this version, there are unresolved questions about the LDAP
1.191 + * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not
1.192 + * clear whether they are appropriate to this application. We have tested only
1.193 + * using servers that do not expect authentication, and that reject BIND
1.194 + * messages. It is not clear what values might be appropriate for the bindname
1.195 + * and authentication fields, which are currently implemented as char strings
1.196 + * supplied by the caller. (If this changes, the API and possibly the templates
1.197 + * will have to change.) Therefore the Client_Create API contains a BindAPI
1.198 + * structure, a union, which will have to be revised and extended when this
1.199 + * area of the protocol is better understood.
1.200 + *
1.201 + * PARAMETERS:
1.202 + * "hostname"
1.203 + * Address of the hostname to be used for the socket connection. Must be
1.204 + * non-NULL.
1.205 + * "timeout"
1.206 + * The PRIntervalTime value to be used as a timeout value in socket calls;
1.207 + * a zero value indicates non-blocking I/O is to be used.
1.208 + * "bindAPI"
1.209 + * The address of a BindAPI to be used if a BIND message is required. If
1.210 + * this argument is NULL, no Bind (or Unbind) will be sent.
1.211 + * "pClient"
1.212 + * Address where object pointer will be stored. 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 CertStore 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_PL_LdapDefaultClient_CreateByName(
1.224 + char *hostname,
1.225 + PRIntervalTime timeout,
1.226 + LDAPBindAPI *bindAPI,
1.227 + PKIX_PL_LdapDefaultClient **pClient,
1.228 + void *plContext);
1.229 +
1.230 +/*
1.231 + * FUNCTION: PKIX_PL_LdapCertStore_Create
1.232 + * DESCRIPTION:
1.233 + *
1.234 + * Creates a new LdapCertStore using the LdapClient pointed to by "client",
1.235 + * and stores the address of the CertStore at "pCertStore".
1.236 + *
1.237 + * PARAMETERS:
1.238 + * "client"
1.239 + * Address of the LdapClient to be used. Must be non-NULL.
1.240 + * "pCertStore"
1.241 + * Address where object pointer will be stored. Must be non-NULL.
1.242 + * "plContext"
1.243 + * Platform-specific context pointer.
1.244 + * THREAD SAFETY:
1.245 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.246 + * RETURNS:
1.247 + * Returns NULL if the function succeeds.
1.248 + * Returns a CertStore Error if the function fails in a non-fatal way.
1.249 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.250 + */
1.251 +PKIX_Error *
1.252 +PKIX_PL_LdapCertStore_Create(
1.253 + PKIX_PL_LdapClient *client,
1.254 + PKIX_CertStore **pCertStore,
1.255 + void *plContext);
1.256 +#endif /* !NSS_PKIX_NO_LDAP */
1.257 +
1.258 +/* PKIX_PL_NssContext
1.259 + *
1.260 + * A PKIX_PL_NssContext provides an example showing how the "plContext"
1.261 + * argument, that is part of every libpkix function call, can be used.
1.262 + * The "plContext" is the Portability Layer Context, which can be used
1.263 + * to communicate layer-specific information from the application to the
1.264 + * underlying Portability Layer (while bypassing the Portable Code, which
1.265 + * blindly passes the plContext on to every function call).
1.266 + *
1.267 + * In this case, NSS serves as both the application and the Portability Layer.
1.268 + * We define an NSS-specific structure, which includes an arena and a number
1.269 + * of SECCertificateUsage bit flags encoded as a PKIX_UInt32. A third argument,
1.270 + * wincx, is used on Windows platforms for PKCS11 access, and should be set to
1.271 + * NULL for other platforms.
1.272 + * Before calling any of the libpkix functions, the caller should create the NSS
1.273 + * context, by calling PKIX_PL_NssContext_Create, and provide that NSS context
1.274 + * as the "plContext" argument in every libpkix function call the caller makes.
1.275 + * When the caller is finished using the NSS context (usually just after he
1.276 + * calls PKIX_Shutdown), the caller should call PKIX_PL_NssContext_Destroy to
1.277 + * free the NSS context structure.
1.278 + */
1.279 +
1.280 +/*
1.281 + * FUNCTION: PKIX_PL_NssContext_Create
1.282 + * DESCRIPTION:
1.283 + *
1.284 + * Creates a new NssContext using the certificate usage(s) specified by
1.285 + * "certUsage" and stores it at "pNssContext". This function also internally
1.286 + * creates an arena and stores it as part of the NssContext structure. Unlike
1.287 + * most other libpkix API functions, this function does not take a "plContext"
1.288 + * parameter.
1.289 + *
1.290 + * PARAMETERS:
1.291 + * "certUsage"
1.292 + * The desired SECCertificateUsage(s).
1.293 + * "useNssArena"
1.294 + * Boolean flag indicates NSS Arena is used for memory allocation.
1.295 + * "wincx"
1.296 + * A Windows-dependent pointer for PKCS11 token handling.
1.297 + * "pNssContext"
1.298 + * Address where object pointer will be stored. Must be non-NULL.
1.299 + * THREAD SAFETY:
1.300 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.301 + * RETURNS:
1.302 + * Returns NULL if the function succeeds.
1.303 + * Returns a Context Error if the function fails in a non-fatal way.
1.304 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.305 + */
1.306 +PKIX_Error *
1.307 +PKIX_PL_NssContext_Create(
1.308 + PKIX_UInt32 certificateUsage,
1.309 + PKIX_Boolean useNssArena,
1.310 + void *wincx,
1.311 + void **pNssContext);
1.312 +
1.313 +/*
1.314 + * FUNCTION: PKIX_PL_NssContext_Destroy
1.315 + * DESCRIPTION:
1.316 + *
1.317 + * Frees the structure pointed to by "nssContext" along with any of its
1.318 + * associated memory. Unlike most other libpkix API functions, this function
1.319 + * does not take a "plContext" parameter.
1.320 + *
1.321 + * PARAMETERS:
1.322 + * "nssContext"
1.323 + * Address of NssContext to be destroyed. Must be non-NULL.
1.324 + * THREAD SAFETY:
1.325 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.326 + * RETURNS:
1.327 + * Returns NULL if the function succeeds.
1.328 + * Returns a Context Error if the function fails in a non-fatal way.
1.329 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.330 + */
1.331 +PKIX_Error *
1.332 +PKIX_PL_NssContext_Destroy(
1.333 + void *nssContext);
1.334 +
1.335 +/*
1.336 + * FUNCTION: PKIX_PL_NssContext_SetTimeout
1.337 + * DESCRIPTION:
1.338 + *
1.339 + * Sets IO timeout for network operations like OCSP response and cert
1.340 + * fetching.
1.341 + *
1.342 + * PARAMETERS:
1.343 + * "nssContext"
1.344 + * Address of NssContext to be destroyed. Must be non-NULL.
1.345 + * THREAD SAFETY:
1.346 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.347 + * RETURNS:
1.348 + * Returns NULL if the function succeeds.
1.349 + * Returns a Context Error if the function fails in a non-fatal way.
1.350 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.351 + */
1.352 +PKIX_Error *
1.353 +PKIX_PL_NssContext_SetTimeout(PKIX_UInt32 timeout, PKIX_PL_NssContext *nssContext);
1.354 +
1.355 +/*
1.356 + * FUNCTION: PKIX_PL_NssContext_SetMaxResponseLen
1.357 + * DESCRIPTION:
1.358 + *
1.359 + * Sets maximum responce length allowed during network IO operations.
1.360 + *
1.361 + * PARAMETERS:
1.362 + * "nssContext"
1.363 + * Address of NssContext to be destroyed. Must be non-NULL.
1.364 + * THREAD SAFETY:
1.365 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.366 + * RETURNS:
1.367 + * Returns NULL if the function succeeds.
1.368 + * Returns a Context Error if the function fails in a non-fatal way.
1.369 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.370 + */
1.371 +PKIX_Error *
1.372 +PKIX_PL_NssContext_SetMaxResponseLen(PKIX_UInt32 len, PKIX_PL_NssContext *nssContext);
1.373 +
1.374 +/*
1.375 + * FUNCTION: PKIX_PL_NssContext_SetCrlReloadDelay
1.376 + * DESCRIPTION:
1.377 + *
1.378 + * Sets user defined timeout between attempts to load crl using
1.379 + * CRLDP.
1.380 + *
1.381 + * PARAMETERS:
1.382 + * "delaySeconds"
1.383 + * Reload delay in seconds.
1.384 + * "nssContext"
1.385 + * Address of NssContext to be destroyed. Must be non-NULL.
1.386 + * THREAD SAFETY:
1.387 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.388 + * RETURNS:
1.389 + * Returns NULL if the function succeeds.
1.390 + * Returns a Context Error if the function fails in a non-fatal way.
1.391 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.392 + */
1.393 +PKIX_Error *
1.394 +PKIX_PL_NssContext_SetCrlReloadDelay(PKIX_UInt32 delaySeconds,
1.395 + PKIX_PL_NssContext *nssContext);
1.396 +
1.397 +/*
1.398 + * FUNCTION: PKIX_PL_NssContext_SetBadDerCrlReloadDelay
1.399 + * DESCRIPTION:
1.400 + *
1.401 + * Sets user defined timeout between attempts to load crls
1.402 + * that failed to decode.
1.403 + *
1.404 + * PARAMETERS:
1.405 + * "delaySeconds"
1.406 + * Reload delay in seconds.
1.407 + * "nssContext"
1.408 + * Address of NssContext to be destroyed. Must be non-NULL.
1.409 + * THREAD SAFETY:
1.410 + * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
1.411 + * RETURNS:
1.412 + * Returns NULL if the function succeeds.
1.413 + * Returns a Context Error if the function fails in a non-fatal way.
1.414 + * Returns a Fatal Error if the function fails in an unrecoverable way.
1.415 + */
1.416 +PKIX_Error *
1.417 +PKIX_PL_NssContext_SetBadDerCrlReloadDelay(PKIX_UInt32 delaySeconds,
1.418 + PKIX_PL_NssContext *nssContext);
1.419 +#ifdef __cplusplus
1.420 +}
1.421 +#endif
1.422 +
1.423 +#endif /* _PKIX_SAMPLEMODULES_H */
