diff options
Diffstat (limited to 'security/nss/lib/libpkix/include/pkix_sample_modules.h')
| -rwxr-xr-x | security/nss/lib/libpkix/include/pkix_sample_modules.h | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/security/nss/lib/libpkix/include/pkix_sample_modules.h b/security/nss/lib/libpkix/include/pkix_sample_modules.h new file mode 100755 index 000000000..75d9618c5 --- /dev/null +++ b/security/nss/lib/libpkix/include/pkix_sample_modules.h @@ -0,0 +1,420 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +/* + * This file defines functions associated with CertStore types. + * + */ + + +#ifndef _PKIX_SAMPLEMODULES_H +#define _PKIX_SAMPLEMODULES_H + +#include "pkix_pl_common.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* General + * + * Please refer to the libpkix Programmer's Guide for detailed information + * about how to use the libpkix library. Certain key warnings and notices from + * that document are repeated here for emphasis. + * + * All identifiers in this file (and all public identifiers defined in + * libpkix) begin with "PKIX_". Private identifiers only intended for use + * within the library begin with "pkix_". + * + * A function returns NULL upon success, and a PKIX_Error pointer upon failure. + * + * Unless otherwise noted, for all accessor (gettor) functions that return a + * PKIX_PL_Object pointer, callers should assume that this pointer refers to a + * shared object. Therefore, the caller should treat this shared object as + * read-only and should not modify this shared object. When done using the + * shared object, the caller should release the reference to the object by + * using the PKIX_PL_Object_DecRef function. + * + * While a function is executing, if its arguments (or anything referred to by + * its arguments) are modified, free'd, or destroyed, the function's behavior + * is undefined. + * + */ + +/* PKIX_PL_CollectionCertStore + * + * A PKIX_CollectionCertStore provides an example for showing how to retrieve + * certificates and CRLs from a repository, such as a directory in the system. + * It is expected the directory is an absolute directory which contains CRL + * and Cert data files. CRL files are expected to have the suffix of .crl + * and Cert files are expected to have the suffix of .crt . + * + * Once the caller has created the CollectionCertStoreContext object, the caller + * then can call pkix_pl_CollectionCertStore_GetCert or + * pkix_pl_CollectionCertStore_GetCRL to obtain Lists of PKIX_PL_Cert or + * PKIX_PL_CRL objects, respectively. + */ + +/* + * FUNCTION: PKIX_PL_CollectionCertStore_Create + * DESCRIPTION: + * + * Creates a new CollectionCertStore and returns it at + * "pColCertStore". + * + * PARAMETERS: + * "storeDir" + * The absolute path where *.crl files are located. + * "pColCertStoreContext" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CollectionCertStoreContext Error if the function fails in + * a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_CollectionCertStore_Create( + PKIX_PL_String *storeDir, + PKIX_CertStore **pCertStore, + void *plContext); + +/* PKIX_PL_PK11CertStore + * + * A PKIX_PL_PK11CertStore retrieves certificates and CRLs from a PKCS11 + * database. The directory that contains the cert8.db, key3.db, and secmod.db + * files that comprise a PKCS11 database are specified in NSS initialization. + * + * Once the caller has created the Pk11CertStore object, the caller can call + * pkix_pl_Pk11CertStore_GetCert or pkix_pl_Pk11CertStore_GetCert to obtain + * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively. + */ + +/* + * FUNCTION: PKIX_PL_Pk11CertStore_Create + * DESCRIPTION: + * + * Creates a new Pk11CertStore and returns it at "pPk11CertStore". + * + * PARAMETERS: + * "pPk11CertStore" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertStore Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_Pk11CertStore_Create( + PKIX_CertStore **pPk11CertStore, + void *plContext); + +#ifndef NSS_PKIX_NO_LDAP +/* PKIX_PL_LdapCertStore + * + * A PKIX_PL_LdapCertStore retrieves certificates and CRLs from an LDAP server + * over a socket connection. It used the LDAP protocol as described in RFC1777. + * + * Once the caller has created the LdapCertStore object, the caller can call + * pkix_pl_LdapCertStore_GetCert or pkix_pl_LdapCertStore_GetCert to obtain + * a List of PKIX_PL_Certs or PKIX_PL_CRL objects, respectively. + */ + +/* + * FUNCTION: PKIX_PL_LdapDefaultClient_Create + * DESCRIPTION: + * + * Creates an LdapDefaultClient using the PRNetAddr poined to by "sockaddr", + * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI"; + * and stores the address of the default LdapClient at "pClient". + * + * At the time of this version, there are unresolved questions about the LDAP + * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not + * clear whether they are appropriate to this application. We have tested only + * using servers that do not expect authentication, and that reject BIND + * messages. It is not clear what values might be appropriate for the bindname + * and authentication fields, which are currently implemented as char strings + * supplied by the caller. (If this changes, the API and possibly the templates + * will have to change.) Therefore the Client_Create API contains a BindAPI + * structure, a union, which will have to be revised and extended when this + * area of the protocol is better understood. + * + * PARAMETERS: + * "sockaddr" + * Address of the PRNetAddr to be used for the socket connection. Must be + * non-NULL. + * "timeout" + * The PRIntervalTime value to be used as a timeout value in socket calls; + * a zero value indicates non-blocking I/O is to be used. + * "bindAPI" + * The address of a BindAPI to be used if a BIND message is required. If + * this argument is NULL, no Bind (or Unbind) will be sent. + * "pClient" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertStore Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_LdapDefaultClient_Create( + PRNetAddr *sockaddr, + PRIntervalTime timeout, + LDAPBindAPI *bindAPI, + PKIX_PL_LdapDefaultClient **pClient, + void *plContext); + +/* + * FUNCTION: PKIX_PL_LdapDefaultClient_CreateByName + * DESCRIPTION: + * + * Creates an LdapDefaultClient using the hostname poined to by "hostname", + * with a timeout value of "timeout", and a BindAPI pointed to by "bindAPI"; + * and stores the address of the default LdapClient at "pClient". + * + * At the time of this version, there are unresolved questions about the LDAP + * protocol. Although RFC1777 describes a BIND and UNBIND message, it is not + * clear whether they are appropriate to this application. We have tested only + * using servers that do not expect authentication, and that reject BIND + * messages. It is not clear what values might be appropriate for the bindname + * and authentication fields, which are currently implemented as char strings + * supplied by the caller. (If this changes, the API and possibly the templates + * will have to change.) Therefore the Client_Create API contains a BindAPI + * structure, a union, which will have to be revised and extended when this + * area of the protocol is better understood. + * + * PARAMETERS: + * "hostname" + * Address of the hostname to be used for the socket connection. Must be + * non-NULL. + * "timeout" + * The PRIntervalTime value to be used as a timeout value in socket calls; + * a zero value indicates non-blocking I/O is to be used. + * "bindAPI" + * The address of a BindAPI to be used if a BIND message is required. If + * this argument is NULL, no Bind (or Unbind) will be sent. + * "pClient" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertStore Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_LdapDefaultClient_CreateByName( + char *hostname, + PRIntervalTime timeout, + LDAPBindAPI *bindAPI, + PKIX_PL_LdapDefaultClient **pClient, + void *plContext); + +/* + * FUNCTION: PKIX_PL_LdapCertStore_Create + * DESCRIPTION: + * + * Creates a new LdapCertStore using the LdapClient pointed to by "client", + * and stores the address of the CertStore at "pCertStore". + * + * PARAMETERS: + * "client" + * Address of the LdapClient to be used. Must be non-NULL. + * "pCertStore" + * Address where object pointer will be stored. Must be non-NULL. + * "plContext" + * Platform-specific context pointer. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a CertStore Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_LdapCertStore_Create( + PKIX_PL_LdapClient *client, + PKIX_CertStore **pCertStore, + void *plContext); +#endif /* !NSS_PKIX_NO_LDAP */ + +/* PKIX_PL_NssContext + * + * A PKIX_PL_NssContext provides an example showing how the "plContext" + * argument, that is part of every libpkix function call, can be used. + * The "plContext" is the Portability Layer Context, which can be used + * to communicate layer-specific information from the application to the + * underlying Portability Layer (while bypassing the Portable Code, which + * blindly passes the plContext on to every function call). + * + * In this case, NSS serves as both the application and the Portability Layer. + * We define an NSS-specific structure, which includes an arena and a number + * of SECCertificateUsage bit flags encoded as a PKIX_UInt32. A third argument, + * wincx, is used on Windows platforms for PKCS11 access, and should be set to + * NULL for other platforms. + * Before calling any of the libpkix functions, the caller should create the NSS + * context, by calling PKIX_PL_NssContext_Create, and provide that NSS context + * as the "plContext" argument in every libpkix function call the caller makes. + * When the caller is finished using the NSS context (usually just after he + * calls PKIX_Shutdown), the caller should call PKIX_PL_NssContext_Destroy to + * free the NSS context structure. + */ + +/* + * FUNCTION: PKIX_PL_NssContext_Create + * DESCRIPTION: + * + * Creates a new NssContext using the certificate usage(s) specified by + * "certUsage" and stores it at "pNssContext". This function also internally + * creates an arena and stores it as part of the NssContext structure. Unlike + * most other libpkix API functions, this function does not take a "plContext" + * parameter. + * + * PARAMETERS: + * "certUsage" + * The desired SECCertificateUsage(s). + * "useNssArena" + * Boolean flag indicates NSS Arena is used for memory allocation. + * "wincx" + * A Windows-dependent pointer for PKCS11 token handling. + * "pNssContext" + * Address where object pointer will be stored. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_Create( + PKIX_UInt32 certificateUsage, + PKIX_Boolean useNssArena, + void *wincx, + void **pNssContext); + +/* + * FUNCTION: PKIX_PL_NssContext_Destroy + * DESCRIPTION: + * + * Frees the structure pointed to by "nssContext" along with any of its + * associated memory. Unlike most other libpkix API functions, this function + * does not take a "plContext" parameter. + * + * PARAMETERS: + * "nssContext" + * Address of NssContext to be destroyed. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_Destroy( + void *nssContext); + +/* + * FUNCTION: PKIX_PL_NssContext_SetTimeout + * DESCRIPTION: + * + * Sets IO timeout for network operations like OCSP response and cert + * fetching. + * + * PARAMETERS: + * "nssContext" + * Address of NssContext to be destroyed. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_SetTimeout(PKIX_UInt32 timeout, PKIX_PL_NssContext *nssContext); + +/* + * FUNCTION: PKIX_PL_NssContext_SetMaxResponseLen + * DESCRIPTION: + * + * Sets maximum responce length allowed during network IO operations. + * + * PARAMETERS: + * "nssContext" + * Address of NssContext to be destroyed. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_SetMaxResponseLen(PKIX_UInt32 len, PKIX_PL_NssContext *nssContext); + +/* + * FUNCTION: PKIX_PL_NssContext_SetCrlReloadDelay + * DESCRIPTION: + * + * Sets user defined timeout between attempts to load crl using + * CRLDP. + * + * PARAMETERS: + * "delaySeconds" + * Reload delay in seconds. + * "nssContext" + * Address of NssContext to be destroyed. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_SetCrlReloadDelay(PKIX_UInt32 delaySeconds, + PKIX_PL_NssContext *nssContext); + +/* + * FUNCTION: PKIX_PL_NssContext_SetBadDerCrlReloadDelay + * DESCRIPTION: + * + * Sets user defined timeout between attempts to load crls + * that failed to decode. + * + * PARAMETERS: + * "delaySeconds" + * Reload delay in seconds. + * "nssContext" + * Address of NssContext to be destroyed. Must be non-NULL. + * THREAD SAFETY: + * Thread Safe (see Thread Safety Definitions in Programmer's Guide) + * RETURNS: + * Returns NULL if the function succeeds. + * Returns a Context Error if the function fails in a non-fatal way. + * Returns a Fatal Error if the function fails in an unrecoverable way. + */ +PKIX_Error * +PKIX_PL_NssContext_SetBadDerCrlReloadDelay(PKIX_UInt32 delaySeconds, + PKIX_PL_NssContext *nssContext); +#ifdef __cplusplus +} +#endif + +#endif /* _PKIX_SAMPLEMODULES_H */ |