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