mirror of
https://github.com/rn10950/RetroZilla.git
synced 2024-11-15 04:00:12 +01:00
419 lines
15 KiB
C
419 lines
15 KiB
C
/* 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);
|
|
|
|
/* 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);
|
|
|
|
/* 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 */
|