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 the PKIX_CertStore type.
andre@0:  *
andre@0:  */
andre@0: 
andre@0: #ifndef _PKIX_CERTSTORE_H
andre@0: #define _PKIX_CERTSTORE_H
andre@0: 
andre@0: #include "pkixt.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_CertStore
andre@0:  *
andre@0:  * A PKIX_CertStore provides a standard way for the caller to retrieve
andre@0:  * certificates and CRLs from a particular repository (or "store") of
andre@0:  * certificates and CRLs, including LDAP directories, flat files, local
andre@0:  * databases, etc. The CertCallback allows custom certificate retrieval logic
andre@0:  * to be used while the CRLCallback allows custom CRL retrieval logic to be
andre@0:  * used. Additionally, a CertStore can be initialized with a certStoreContext,
andre@0:  * which is where the caller can specify configuration data such as the host
andre@0:  * name of an LDAP server. Note that this certStoreContext must be an
andre@0:  * Object (although any object type), allowing it to be reference-counted and
andre@0:  * allowing it to provide the standard Object functions (Equals, Hashcode,
andre@0:  * ToString, Compare, Duplicate). Please note that each certStoreContext must
andre@0:  * provide Equals and Hashcode functions in order for the caching (on Cert and
andre@0:  * CertChain) to work correctly. When providing those two functions, it is not
andre@0:  * required that all the components of the object be hashed or checked for 
andre@0:  * equality, but merely that the functions distinguish between unique
andre@0:  * instances of the certStoreContext.
andre@0:  *
andre@0:  * Once the caller has created the CertStore object, the caller then specifies
andre@0:  * these CertStore objects in a ProcessingParams object and passes that object
andre@0:  * to PKIX_ValidateChain or PKIX_BuildChain, which uses the objects to call the
andre@0:  * user's callback functions as needed during the validation or building
andre@0:  * process.
andre@0:  *
andre@0:  * The order of CertStores stored (as a list) at ProcessingParams determines
andre@0:  * the order in which certificates are retrieved. Trusted CertStores should
andre@0:  * precede non-trusted ones on the list of CertStores so their certificates
andre@0:  * are evaluated ahead of other certificates selected on the basis of the same
andre@0:  * selector criteria.
andre@0:  *
andre@0:  * The CheckTrustCallback function is used when the CertStore object
andre@0:  * supports trust status, which means a Cert's trust status can be altered
andre@0:  * dynamically. When a CertStore object is created, if the
andre@0:  * CheckTrustCallback is initialized to be non-NULL, this CertStore is
andre@0:  * defaulted as supporting trust. Then whenever a Cert needs to (re)check its
andre@0:  * trust status, this callback can be invoked. When a Cert is retrieved by
andre@0:  * a CertStore supports trust, at its GetCertCallback, the CertStore
andre@0:  * information should be updated in Cert's data structure so the link between
andre@0:  * the Cert and CertStore exists.
andre@0:  *
andre@0:  */
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CertCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function retrieves from the CertStore pointed to by "store"
andre@0:  *  all the certificates that match the CertSelector pointed to by "selector".
andre@0:  *  It places these certificates in a List and stores a pointer to the List at
andre@0:  *  "pCerts". If no certificates are found which match the CertSelector's
andre@0:  *  criteria, this function stores an empty List at "pCerts". In either case, if
andre@0:  *  the operation is completed, NULL is stored at "pNBIOContext".
andre@0:  *
andre@0:  *  A CertStore which uses non-blocking I/O may store platform-dependent
andre@0:  *  information at "pNBIOContext" and NULL at "pCerts" to indicate that I/O is
andre@0:  *  pending. A subsequent call to PKIX_CertStore_CertContinue is required to
andre@0:  *  finish the operation and to obtain the List of Certs.
andre@0:  *
andre@0:  *  Note that the List returned by this function is immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which Certs are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "selector"
andre@0:  *      Address of CertSelector whose criteria must be satisfied.
andre@0:  *      Must be non-NULL.
andre@0:  *  "verifyNode"
andre@0:  *      Parent log node for tracking of filtered out certs.
andre@0:  *  "pNBIOContext"
andre@0:  *      Address at which platform-dependent information is stored if the
andre@0:  *      operation is suspended for non-blocking I/O. Must be non-NULL.
andre@0:  *  "pCerts"
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
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CertCallback)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertSelector *selector,
andre@0:         PKIX_VerifyNode *verifyNode,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCerts,  /* list of PKIX_PL_Cert */
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CertContinue
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This function continues the non-blocking operation initiated by an earlier
andre@0:  *  call to the CertCallback function, for the CertStore pointed to by "store". 
andre@0:  *  If an earlier call did not terminate with the WOULDBLOCK indication (non-NULL
andre@0:  *  value returned in "pNBIOContext") calling this function will return a fatal
andre@0:  *  error. If the operation is completed the certificates found are placed in a
andre@0:  *  List, a pointer to which is stored at "pCerts". If no certificates are found
andre@0:  *  which match the CertSelector's criteria, this function stores an empty List
andre@0:  *  at "pCerts". In either case, if the operation is completed, NULL is stored
andre@0:  *  at "pNBIOContext".
andre@0:  *
andre@0:  *  If non-blocking I/O is still pending this function stores platform-dependent
andre@0:  *  information at "pNBIOContext" and NULL at "pCerts". A subsequent call to
andre@0:  *  PKIX_CertStore_CertContinue is required to finish the operation and to
andre@0:  *  obtain the List of Certs.
andre@0:  *
andre@0:  *  Note that the List returned by this function is immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which Certs are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "selector"
andre@0:  *      Address of CertSelector whose criteria must be satisfied.
andre@0:  *      Must be non-NULL.
andre@0:  *  "verifyNode"
andre@0:  *      Parent log node for tracking of filtered out certs.
andre@0:  *  "pNBIOContext"
andre@0:  *      Address at which platform-dependent information is stored if the
andre@0:  *      operation is suspended for non-blocking I/O. Must be non-NULL.
andre@0:  *  "pCerts"
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
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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_CertStore_CertContinue(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertSelector *selector,
andre@0:         PKIX_VerifyNode *verifyNode,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCerts,  /* list of PKIX_PL_Cert */
andre@0:         void *plContext);
andre@0: 
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CertContinueFunction)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertSelector *selector,
andre@0:         PKIX_VerifyNode *verifyNode,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCerts,  /* list of PKIX_PL_Cert */
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CRLCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function retrieves from the CertStore pointed to by "store"
andre@0:  *  all the CRLs that match the CRLSelector pointed to by "selector". It
andre@0:  *  places these CRLs in a List and stores a pointer to the List at "pCRLs".
andre@0:  *  If no CRLs are found which match the CRLSelector's criteria, this function
andre@0:  *  stores an empty List at "pCRLs". In either case, if the operation is
andre@0:  *  completed, NULL is stored at "pNBIOContext".
andre@0:  *
andre@0:  *  A CertStore which uses non-blocking I/O may store platform-dependent
andre@0:  *  information at "pNBIOContext" and NULL at "pCrls" to indicate that I/O is
andre@0:  *  pending. A subsequent call to PKIX_CertStore_CRLContinue is required to
andre@0:  *  finish the operation and to obtain the List of Crls.
andre@0:  *
andre@0:  *  Note that the List returned by this function is immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which CRLs are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "selector"
andre@0:  *      Address of CRLSelector whose criteria must be satisfied.
andre@0:  *      Must be non-NULL.
andre@0:  *  "pCrls"
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
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CRLCallback)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CRLSelector *selector,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCrls,  /* list of PKIX_PL_CRL */
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_ImportCrlCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  * The function imports crl list into a cert store. Stores that
andre@0:  * have local cache may only have that function defined.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which CRLs are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "issuerName"
andre@0:  *      Name of the issuer that will be used to track bad der crls.
andre@0:  *  "crlList"
andre@0:  *      Address on the importing crl list.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_ImportCrlCallback)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_PL_X500Name *issuerName,
andre@0:         PKIX_List *crlList,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CheckRevokationByCrlCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  * The function checks revocation status of a cert with specified
andre@0:  * issuer, date. It returns revocation status of a cert and
andre@0:  * a reason code(if any) if a cert was revoked.
andre@0:  * 
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which CRLs are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "cert"
andre@0:  *      Certificate which revocation status will be checked.
andre@0:  *  "issuer"
andre@0:  *      Issuer certificate of the "crl".
andre@0:  *  "date"
andre@0:  *      Date of the revocation check.
andre@0:  *  "crlDownloadDone"
andre@0:  *      Indicates, that all needed crl downloads are done by the time of
andre@0:  *      the revocation check.
andre@0:  *  "reasonCode"
andre@0:  *      If cert is revoked, returned reason code for  which a cert was revoked.
andre@0:  *  "revStatus"
andre@0:  *      Returned revocation status of the cert. See PKIX_RevocationStatus
andre@0:  *      for more details
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CheckRevokationByCrlCallback)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_PL_Cert *cert,
andre@0:         PKIX_PL_Cert *issuer,
andre@0:         PKIX_PL_Date *date,
andre@0:         PKIX_Boolean  crlDownloadDone,
andre@0:         PKIX_UInt32 *reasonCode,
andre@0:         PKIX_RevocationStatus *revStatus,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CrlContinue
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This function continues the non-blocking operation initiated by an earlier
andre@0:  *  call to the CRLCallback function, for the CertStore pointed to by "store". 
andre@0:  *  If an earlier call did not terminate with the WOULDBLOCK indication (non-NULL
andre@0:  *  value returned in "pNBIOContext") calling this function will return a fatal
andre@0:  *  error. If the operation is completed the crls found are placed in a List, a
andre@0:  *  pointer to which is stored at "pCrls". If no crls are found which match the
andre@0:  *  CRLSelector's criteria, this function stores an empty List at "pCrls". In
andre@0:  *  either case, if the operation is completed, NULL is stored at "pNBIOContext".
andre@0:  *
andre@0:  *  If non-blocking I/O is still pending this function stores platform-dependent
andre@0:  *  information at "pNBIOContext" and NULL at "pCrls". A subsequent call to
andre@0:  *  PKIX_CertStore_CrlContinue is required to finish the operation and to
andre@0:  *  obtain the List of Crls.
andre@0:  *
andre@0:  *  Note that the List returned by this function is immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which Crls are to be retrieved.
andre@0:  *      Must be non-NULL.
andre@0:  *  "selector"
andre@0:  *      Address of CRLSelector whose criteria must be satisfied.
andre@0:  *      Must be non-NULL.
andre@0:  *  "pNBIOContext"
andre@0:  *      Address at which platform-dependent information is stored if the
andre@0:  *      operation is suspended for non-blocking I/O. Must be non-NULL.
andre@0:  *  "pCrls"
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
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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_CertStore_CrlContinue(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CRLSelector *selector,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCrls,  /* list of PKIX_PL_CRL */
andre@0:         void *plContext);
andre@0: 
andre@0: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CrlContinueFunction)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CRLSelector *selector,
andre@0:         void **pNBIOContext,
andre@0:         PKIX_List **pCrls,  /* list of PKIX_PL_CRL */
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_CheckTrustCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  This callback function rechecks "cert's" trust status from the CertStore
andre@0:  *  pointed to by "store".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore from which Certs are to be checked.
andre@0:  *      Must be non-NULL.
andre@0:  *  "cert"
andre@0:  *      Address of Cert whose trust status needs to be rechecked.
andre@0:  *      Must be non-NULL.
andre@0:  *  "pTrusted"
andre@0:  *      Address of PKIX_Boolean where the trust status is returned.
andre@0:  *      Must be non-NULL.
andre@0:  *  "plContext"
andre@0:  *      Platform-specific context pointer.
andre@0:  * THREAD SAFETY:
andre@0:  *  Thread Safe
andre@0:  *
andre@0:  *  Multiple threads must be able to safely call this function without
andre@0:  *  worrying about conflicts, even if they're operating on the same object.
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: typedef PKIX_Error *
andre@0: (*PKIX_CertStore_CheckTrustCallback)(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_PL_Cert *cert,
andre@0:         PKIX_Boolean *pTrusted,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_Create
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Creates a new CertStore and stores it at "pStore". The new CertStore uses
andre@0:  *  the CertCallback pointed to by "certCallback" and the CRLCallback pointed
andre@0:  *  to by "crlCallback" as its callback functions and uses the Object pointed
andre@0:  *  to by "certStoreContext" as its context . Note that this certStoreContext
andre@0:  *  must be an Object (although any object type), allowing it to be
andre@0:  *  reference-counted and allowing it to provide the standard Object functions
andre@0:  *  (Equals, Hashcode, ToString, Compare, Duplicate). Once created, a
andre@0:  *  CertStore object is immutable, although the underlying repository can
andre@0:  *  change. For example, a CertStore will often be a front-end for a database
andre@0:  *  or directory. The contents of that directory can change after the
andre@0:  *  CertStore object is created, but the CertStore object remains immutable.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "certCallback"
andre@0:  *      The CertCallback function to be used. Must be non-NULL.
andre@0:  *  "crlCallback"
andre@0:  *      The CRLCallback function to be used. Must be non-NULL.
andre@0:  *  "certContinue"
andre@0:  *      The function to be used to resume a certCallback that returned with a
andre@0:  *      WOULDBLOCK condition. Must be non-NULL if certStore supports non-blocking
andre@0:  *      I/O.
andre@0:  *  "crlContinue"
andre@0:  *      The function to be used to resume a crlCallback that returned with a
andre@0:  *      WOULDBLOCK condition. Must be non-NULL if certStore supports non-blocking
andre@0:  *      I/O.
andre@0:  *  "trustCallback"
andre@0:  *      Address of PKIX_CertStore_CheckTrustCallback which is called to
andre@0:  *      verify the trust status of Certs in this CertStore.
andre@0:  *  "certStoreContext"
andre@0:  *      Address of Object representing the CertStore's context (if any).
andre@0:  *  "cachedFlag"
andre@0:  *      If TRUE indicates data retrieved from CertStore should be cached.
andre@0:  *  "localFlag"
andre@0:  *      Boolean value indicating whether this CertStore is local.
andre@0:  *  "pStore"
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_CertStore_Create(
andre@0:         PKIX_CertStore_CertCallback certCallback,
andre@0:         PKIX_CertStore_CRLCallback crlCallback,
andre@0:         PKIX_CertStore_CertContinueFunction certContinue,
andre@0:         PKIX_CertStore_CrlContinueFunction crlContinue,
andre@0:         PKIX_CertStore_CheckTrustCallback trustCallback,
andre@0:         PKIX_CertStore_ImportCrlCallback importCrlCallback,
andre@0:         PKIX_CertStore_CheckRevokationByCrlCallback checkRevByCrlCallback,
andre@0:         PKIX_PL_Object *certStoreContext,
andre@0:         PKIX_Boolean cachedFlag,
andre@0:         PKIX_Boolean localFlag,
andre@0:         PKIX_CertStore **pStore,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetCertCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves a pointer to "store's" Cert callback function and put it in
andre@0:  *  "pCallback".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose Cert callback is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where Cert callback function pointer will be stored.
andre@0:  *      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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetCertCallback(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertStore_CertCallback *pCallback,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetCRLCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves a pointer to "store's" CRL callback function and put it in
andre@0:  *  "pCallback".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose CRL callback is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where CRL callback function pointer will be stored.
andre@0:  *      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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetCRLCallback(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertStore_CRLCallback *pCallback,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetImportCrlCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves a pointer to "store's" Import CRL callback function and put it in
andre@0:  *  "pCallback".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose CRL callback is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where CRL callback function pointer will be stored.
andre@0:  *      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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetImportCrlCallback(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertStore_ImportCrlCallback *pCallback,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetCheckRevByCrl
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves a pointer to "store's" CRL revocation checker callback function
andre@0:  *  and put it in "pCallback".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose CRL callback is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where CRL callback function pointer will be stored.
andre@0:  *      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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetCrlCheckerFn(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertStore_CheckRevokationByCrlCallback *pCallback,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetTrustCallback
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the function pointer to the CheckTrust callback function of the
andre@0:  *  CertStore pointed to by "store" and stores it at "pCallback".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose CheckTrust callback is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where CheckTrust callback function pointer will be stored.
andre@0:  *      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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetTrustCallback(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_CertStore_CheckTrustCallback *pCallback,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetCertStoreContext
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves a pointer to the Object representing the context (if any)
andre@0:  *  of the CertStore pointed to by "store" and stores it at
andre@0:  *  "pCertStoreContext".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore whose context is to be stored. Must be non-NULL.
andre@0:  *  "pCertStoreContext"
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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetCertStoreContext(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_PL_Object **pCertStoreContext,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetCertStoreCacheFlag
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the Boolean cache flag of the CertStore pointed to by "store" and
andre@0:  *  stores it at "pCachedFlag".
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      Address of CertStore whose cache flag is to be stored. Must be non-NULL.
andre@0:  *  "pCacheFlag"
andre@0:  *      Address where the result 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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetCertStoreCacheFlag(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_Boolean *pCacheFlag,
andre@0:         void *plContext);
andre@0: 
andre@0: /*
andre@0:  * FUNCTION: PKIX_CertStore_GetLocalFlag
andre@0:  * DESCRIPTION:
andre@0:  *
andre@0:  *  Retrieves the Boolean localFlag for the CertStore pointed to by "store" and
andre@0:  *  stores it at "pLocalFlag". The localFlag is TRUE if the CertStore can
andre@0:  *  fulfill a request without performing network I/O.
andre@0:  *
andre@0:  * PARAMETERS:
andre@0:  *  "store"
andre@0:  *      The CertStore whose Local flag is desired. Must be non-NULL.
andre@0:  *  "pCallback"
andre@0:  *      Address where the Boolean LocalFlag 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 Fatal Error if the function fails in an unrecoverable way.
andre@0:  */
andre@0: PKIX_Error *
andre@0: PKIX_CertStore_GetLocalFlag(
andre@0:         PKIX_CertStore *store,
andre@0:         PKIX_Boolean *pLocalFlag,
andre@0:         void *plContext);
andre@0: 
andre@0: #ifdef __cplusplus
andre@0: }
andre@0: #endif
andre@0: 
andre@0: #endif /* _PKIX_CERTSTORE_H */