michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: /*
michael@0:  * This file defines functions associated with the various parameters used
michael@0:  * by the top-level functions.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: #ifndef _PKIX_PARAMS_H
michael@0: #define _PKIX_PARAMS_H
michael@0: 
michael@0: #include "pkixt.h"
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: /* General
michael@0:  *
michael@0:  * Please refer to the libpkix Programmer's Guide for detailed information
michael@0:  * about how to use the libpkix library. Certain key warnings and notices from
michael@0:  * that document are repeated here for emphasis.
michael@0:  *
michael@0:  * All identifiers in this file (and all public identifiers defined in
michael@0:  * libpkix) begin with "PKIX_". Private identifiers only intended for use
michael@0:  * within the library begin with "pkix_".
michael@0:  *
michael@0:  * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
michael@0:  *
michael@0:  * Unless otherwise noted, for all accessor (gettor) functions that return a
michael@0:  * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
michael@0:  * shared object. Therefore, the caller should treat this shared object as
michael@0:  * read-only and should not modify this shared object. When done using the
michael@0:  * shared object, the caller should release the reference to the object by
michael@0:  * using the PKIX_PL_Object_DecRef function.
michael@0:  *
michael@0:  * While a function is executing, if its arguments (or anything referred to by
michael@0:  * its arguments) are modified, free'd, or destroyed, the function's behavior
michael@0:  * is undefined.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: /* PKIX_ProcessingParams
michael@0:  *
michael@0:  * PKIX_ProcessingParams are parameters used when validating or building a
michael@0:  * chain of certificates. Using the parameters, the caller can specify several
michael@0:  * things, including the various inputs to the PKIX chain validation
michael@0:  * algorithm (such as trust anchors, initial policies, etc), any customized
michael@0:  * functionality (such as CertChainCheckers, RevocationCheckers, CertStores),
michael@0:  * and whether revocation checking should be disabled.
michael@0:  *
michael@0:  * Once the caller has created the ProcessingParams object, the caller then
michael@0:  * passes it to PKIX_ValidateChain or PKIX_BuildChain, which uses it to call
michael@0:  * the user's callback functions as needed during the validation or building
michael@0:  * process.
michael@0:  *
michael@0:  * If a parameter is not set (or is set to NULL), it will be set to the
michael@0:  * default value for that parameter. The default value for the Date parameter
michael@0:  * is NULL, which indicates the current time when the path is validated. The
michael@0:  * default for the remaining parameters is the least constrained.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new ProcessingParams object. Trust anchor list is set to
michael@0:  *  newly created empty list of trust. In this case trust anchors will
michael@0:  *  be taken from provided cert store. Pointed to the created
michael@0:  *  ProcessingParams object is stored in "pParams".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "anchors"
michael@0:  *      Address of List of (non-empty) TrustAnchors to be used.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pParams"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_Create(
michael@0:         PKIX_ProcessingParams **pParams,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetCertChainCheckers
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of CertChainCheckers (if any) that are set
michael@0:  *  in the ProcessingParams pointed to by "params" and stores it at
michael@0:  *  "pCheckers". Each CertChainChecker represents a custom certificate
michael@0:  *  validation check used by PKIX_ValidateChain or PKIX_BuildChain as needed
michael@0:  *  during the validation or building process. If "params" does not have any
michael@0:  *  CertChainCheckers, this function stores an empty List at "pCheckers".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of CertChainCheckers (if any)
michael@0:  *      are to be stored. Must be non-NULL.
michael@0:  *  "pCheckers"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetCertChainCheckers(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List **pCheckers, /* list of PKIX_CertChainChecker */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetCertChainCheckers
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a List of
michael@0:  *  CertChainCheckers pointed to by "checkers". Each CertChainChecker
michael@0:  *  represents a custom certificate validation check used by
michael@0:  *  PKIX_ValidateChain or PKIX_BuildChain as needed during the validation or
michael@0:  *  building process. If "checkers" is NULL, no CertChainCheckers will be used.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of CertChainCheckers is to be
michael@0:  *      set. Must be non-NULL.
michael@0:  *  "checkers"
michael@0:  *      Address of List of CertChainCheckers to be set. If NULL, no
michael@0:  *      CertChainCheckers will be used.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params" and "checkers"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetCertChainCheckers(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List *checkers,  /* list of PKIX_CertChainChecker */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_AddCertChainChecker
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Adds the CertChainChecker pointed to by "checker" to the ProcessingParams
michael@0:  *  pointed to by "params". The CertChainChecker represents a custom
michael@0:  *  certificate validation check used by PKIX_ValidateChain or PKIX_BuildChain
michael@0:  *  as needed during the validation or building process.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be added to. Must be non-NULL.
michael@0:  *  "checker"
michael@0:  *      Address of CertChainChecker to be added. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_AddCertChainChecker(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_CertChainChecker *checker,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetRevocationChecker
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the RevocationChecker that are set
michael@0:  *  in the ProcessingParams pointed to by "params" and stores it at
michael@0:  *  "pRevChecker". Each RevocationChecker represents a revocation
michael@0:  *  check used by PKIX_ValidateChain or PKIX_BuildChain as needed during the
michael@0:  *  validation or building process. If "params" does not have any
michael@0:  *  RevocationCheckers, this function stores an empty List at "pRevChecker".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of RevocationCheckers
michael@0:  *      is to be stored. Must be non-NULL.
michael@0:  *  "pRevChecker"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetRevocationChecker(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_RevocationChecker **pChecker,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetRevocationChecker
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a 
michael@0:  *  RevocationChecker pointed to by "revChecker". Revocation
michael@0:  *  checker object should be created and assigned to processing
michael@0:  *  parameters before chain build or validation can begin.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of RevocationCheckers is to be
michael@0:  *      set. Must be non-NULL.
michael@0:  *  "revChecker"
michael@0:  *      Address of RevocationChecker to be set. Must be set before chain
michael@0:  *      building or validation.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetRevocationChecker(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_RevocationChecker *revChecker,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetCertStores
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of CertStores (if any) that are set in the
michael@0:  *  ProcessingParams pointed to by "params" and stores it at "pStores". Each
michael@0:  *  CertStore represents a particular repository from which certificates and
michael@0:  *  CRLs can be retrieved by PKIX_ValidateChain or PKIX_BuildChain as needed
michael@0:  *  during the validation or building process. If "params" does not have any
michael@0:  *  CertStores, this function stores an empty List at "pStores".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of CertStores (if any) are to
michael@0:  *      be stored. Must be non-NULL.
michael@0:  *  "pStores"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetCertStores(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List **pStores,  /* list of PKIX_CertStore */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetCertStores
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a List of CertStores
michael@0:  *  pointed to by "stores". Each CertStore represents a particular repository
michael@0:  *  from which certificates and CRLs can be retrieved by PKIX_ValidateChain or
michael@0:  *  PKIX_BuildChain as needed during the validation or building process. If
michael@0:  *  "stores" is NULL, no CertStores will be used.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of CertStores is to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "stores"
michael@0:  *      Address of List of CertStores to be set. If NULL, no CertStores will
michael@0:  *      be used.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetCertStores(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List *stores,  /* list of PKIX_CertStore */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_AddCertStore
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Adds the CertStore pointed to by "store" to the ProcessingParams pointed
michael@0:  *  to by "params". The CertStore represents a particular repository from
michael@0:  *  which certificates and CRLs can be retrieved by PKIX_ValidateChain or
michael@0:  *  PKIX_BuildChain as needed during the validation or building process.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be added to. Must be non-NULL.
michael@0:  *  "store"
michael@0:  *      Address of CertStore to be added.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_AddCertStore(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_CertStore *store,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetDate
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the Date (if any) that is set in the
michael@0:  *  ProcessingParams pointed to by "params" and stores it at "pDate". The
michael@0:  *  Date represents the time for which the validation of the certificate chain
michael@0:  *  should be determined. If "params" does not have any Date set, this function
michael@0:  *  stores NULL at "pDate".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose Date (if any) is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pDate"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetDate(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_PL_Date **pDate,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetDate
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a Date pointed to by
michael@0:  *  "date". The Date represents the time for which the validation of the
michael@0:  *  certificate chain should be determined. If "date" is NULL, the current
michael@0:  *  time is used during validation.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose Date is to be set. Must be non-NULL.
michael@0:  *  "date"
michael@0:  *      Address of Date to be set. If NULL, current time is used.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetDate(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_PL_Date *date,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetInitialPolicies
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of OIDs (if any) that are set in the
michael@0:  *  ProcessingParams pointed to by "params" and stores it at "pInitPolicies".
michael@0:  *  Each OID represents an initial policy identifier, indicating that any
michael@0:  *  one of these policies would be acceptable to the certificate user for
michael@0:  *  the purposes of certification path processing. If "params" does not have
michael@0:  *  any initial policies, this function stores an empty List at
michael@0:  *  "pInitPolicies".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of OIDs (if any) are to be
michael@0:  *      stored. Must be non-NULL.
michael@0:  *  "pInitPolicies"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetInitialPolicies(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List **pInitPolicies,    /* list of PKIX_PL_OID */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetInitialPolicies
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a List of OIDs
michael@0:  *  pointed to by "initPolicies".
michael@0:  *
michael@0:  *  Each OID represents an initial policy identifier, indicating that any
michael@0:  *  one of these policies would be acceptable to the certificate user for
michael@0:  *  the purposes of certification path processing. By default, any policy
michael@0:  *  is acceptable (i.e. all policies), so a user that wants to allow any
michael@0:  *  policy as acceptable does not need to call this method. Similarly, if
michael@0:  *  initPolicies is NULL or points to an empty List, all policies are
michael@0:  *  acceptable.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of OIDs is to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "initPolicies"
michael@0:  *      Address of List of OIDs to be set. If NULL or if pointing to an empty
michael@0:  *      List, all policies are acceptable.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetInitialPolicies(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List *initPolicies,    /* list of PKIX_PL_OID */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetPolicyQualifiersRejected
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the ProcessingParams pointed to by "params" indicate that
michael@0:  *  policy qualifiers should be rejected and stores the Boolean result at
michael@0:  *  "pRejected".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams used to determine whether or not policy
michael@0:  *      qualifiers should be rejected. Must be non-NULL.
michael@0:  *  "pRejected"
michael@0:  *      Address where Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetPolicyQualifiersRejected(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pRejected,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetPolicyQualifiersRejected
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Specifies in the ProcessingParams pointed to by "params" whether policy
michael@0:  *  qualifiers are rejected using the Boolean value of "rejected".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be set. Must be non-NULL.
michael@0:  *  "rejected"
michael@0:  *      Boolean value indicating whether policy qualifiers are to be rejected.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetPolicyQualifiersRejected(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean rejected,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetTargetCertConstraints
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the CertSelector (if any) that is set in the
michael@0:  *  ProcessingParams pointed to by "params" and stores it at "pConstraints".
michael@0:  *  The CertSelector represents the constraints to be placed on the target
michael@0:  *  certificate. If "params" does not have any CertSelector set, this function
michael@0:  *  stores NULL at "pConstraints".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose CertSelector (if any) is to be
michael@0:  *      stored. Must be non-NULL.
michael@0:  *  "pConstraints"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetTargetCertConstraints(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_CertSelector **pConstraints,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetTargetCertConstraints
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a CertSelector
michael@0:  *  pointed to by "constraints". The CertSelector represents the constraints
michael@0:  *  to be placed on the target certificate. If "constraints" is NULL, no
michael@0:  *  constraints are defined.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose CertSelector is to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "constraints"
michael@0:  *      Address of CertSelector to be set. If NULL, no constraints are defined.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetTargetCertConstraints(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_CertSelector *constraints,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetTrustAnchors
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of TrustAnchors that are set in
michael@0:  *  the ProcessingParams pointed to by "params" and stores it at "pAnchors".
michael@0:  *  If the function succeeds, the pointer to the List is guaranteed to be
michael@0:  *  non-NULL and the List is guaranteed to be non-empty.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of TrustAnchors are to
michael@0:  *      be stored. Must be non-NULL.
michael@0:  *  "pAnchors"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetTrustAnchors(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List **pAnchors,  /* list of TrustAnchor */
michael@0:         void *plContext);
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetTrustAnchors
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  * Sets user defined set of trust anchors. The handling of the trust anchors
michael@0:  * may be furthered alter via PKIX_ProcessingParams_SetUseOnlyTrustAnchors.
michael@0:  * By default, a certificate will be considered invalid if it does not chain
michael@0:  * to a trusted anchor from this list.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of TrustAnchors are to
michael@0:  *      be stored. Must be non-NULL.
michael@0:  *  "anchors"
michael@0:  *      Address of the trust anchors list object. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetTrustAnchors(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List *pAnchors,  /* list of TrustAnchor */
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetUseOnlyTrustAnchors
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  * Retrieves a pointer to the Boolean. The boolean value represents
michael@0:  * the switch value that is used to identify whether trust anchors, if
michael@0:  * specified, should be the exclusive source of trust information.
michael@0:  * If the function succeeds, the pointer to the Boolean is guaranteed to be
michael@0:  * non-NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams. Must be non-NULL.
michael@0:  *  "pUseOnlyTrustAnchors"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetUseOnlyTrustAnchors(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pUseOnlyTrustAnchors,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetUseOnlyTrustAnchors
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  * Configures whether trust anchors are used as the exclusive source of trust.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams. Must be non-NULL.
michael@0:  *  "useOnlyTrustAnchors"
michael@0:  *      If true, indicates that trust anchors should be used exclusively when
michael@0:  *      they have been specified via PKIX_ProcessingParams_SetTrustAnchors. A
michael@0:  *      certificate will be considered invalid if it does not chain to a
michael@0:  *      trusted anchor from that list.
michael@0:  *      If false, indicates that the trust anchors are additive to whatever
michael@0:  *      existing trust stores are configured. A certificate is considered
michael@0:  *      valid if it chains to EITHER a trusted anchor from that list OR a
michael@0:  *      certificate marked trusted in a trust store.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetUseOnlyTrustAnchors(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean useOnlyTrustAnchors,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetUseAIAForCertFetching
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the Boolean. The boolean value represents
michael@0:  *  the switch value that is used to identify if url in cert AIA extension
michael@0:  *  may be used for cert fetching.
michael@0:  *  If the function succeeds, the pointer to the Boolean is guaranteed to be
michael@0:  *  non-NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams. Must be non-NULL.
michael@0:  *  "pUseAIA"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetUseAIAForCertFetching(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pUseAIA,  /* list of TrustAnchor */
michael@0:         void *plContext);
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetTrustAnchors
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  * Sets switch value that defines if url in cert AIA extension
michael@0:  * may be used for cert fetching.
michael@0:  * 
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams.
michael@0:  *  "useAIA"
michael@0:  *      Address of the trust anchors list object. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetUseAIAForCertFetching(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean useAIA,  
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetQualifyTargetCert
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  * Sets a boolean value that tells if libpkix needs to check that
michael@0:  * the target certificate satisfies the conditions set in processing
michael@0:  * parameters. Includes but not limited to date, ku and eku checks.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of TrustAnchors are to
michael@0:  *      be stored. Must be non-NULL.
michael@0:  *  "qualifyTargetCert"
michael@0:  *      boolean value if set to true will trigger qualification of the
michael@0:  *      target certificate.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetQualifyTargetCert(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean qualifyTargetCert,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetHintCerts
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to a List of Certs supplied by the user as a suggested
michael@0:  *  partial CertChain (subject to verification), that are set in the
michael@0:  *  ProcessingParams pointed to by "params", and stores it at "pHintCerts".
michael@0:  *  The List returned may be empty or NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of TrustAnchors are to
michael@0:  *      be stored. Must be non-NULL.
michael@0:  *  "pHintCerts"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetHintCerts(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List **pHintCerts,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetHintCerts
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Stores a pointer to a List of Certs supplied by the user as a suggested
michael@0:  *  partial CertChain (subject to verification), as an element in the
michael@0:  *  ProcessingParams pointed to by "params". The List may be empty or NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose List of HintCerts is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "hintCerts"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetHintCerts(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_List *hintCerts,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_GetResourceLimits
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the ResourceLimits (if any) that is set in the
michael@0:  *  ProcessingParams pointed to by "params" and stores it at "pResourceLimits".
michael@0:  *  The ResourceLimits represent the maximum resource usage that the caller 
michael@0:  *  desires (such as MaxTime). The ValidateChain or BuildChain call will not
michael@0:  *  exceed these maximum limits. If "params" does not have any ResourceLimits
michael@0:  *  set, this function stores NULL at "pResourceLimits".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose ResourceLimits (if any) are to be
michael@0:  *      stored. Must be non-NULL.
michael@0:  *  "pResourceLimits"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_GetResourceLimits(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_ResourceLimits **pResourceLimits,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetResourceLimits
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the ProcessingParams pointed to by "params" with a ResourceLimits
michael@0:  *  object pointed to by "resourceLimits". The ResourceLimits represent the
michael@0:  *  maximum resource usage that the caller desires (such as MaxTime). The
michael@0:  *  ValidateChain or BuildChain call will not exceed these maximum limits.
michael@0:  *  If "resourceLimits" is NULL, no ResourceLimits are defined.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams whose ResourceLimits are to be set.
michael@0:  *      Must be non-NULL.
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits to be set. If NULL, no limits are defined.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetResourceLimits(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_IsAnyPolicyInhibited
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the ProcessingParams pointed to by "params" indicate that
michael@0:  *  anyPolicy is inhibited and stores the Boolean result at "pInhibited".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams used to determine whether or not anyPolicy
michael@0:  *      inhibited. Must be non-NULL.
michael@0:  *  "pInhibited"
michael@0:  *      Address where Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_IsAnyPolicyInhibited(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pInhibited,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetAnyPolicyInhibited
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Specifies in the ProcessingParams pointed to by "params" whether anyPolicy
michael@0:  *  is inhibited using the Boolean value of "inhibited".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be set. Must be non-NULL.
michael@0:  *  "inhibited"
michael@0:  *      Boolean value indicating whether anyPolicy is to be inhibited.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetAnyPolicyInhibited(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean inhibited,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_IsExplicitPolicyRequired
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the ProcessingParams pointed to by "params" indicate that
michael@0:  *  explicit policies are required and stores the Boolean result at
michael@0:  *  "pRequired".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams used to determine whether or not explicit
michael@0:  *      policies are required. Must be non-NULL.
michael@0:  *  "pRequired"
michael@0:  *      Address where Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_IsExplicitPolicyRequired(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pRequired,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetExplicitPolicyRequired
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Specifies in the ProcessingParams pointed to by "params" whether explicit
michael@0:  *  policies are required using the Boolean value of "required".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be set. Must be non-NULL.
michael@0:  *  "required"
michael@0:  *      Boolean value indicating whether explicit policies are to be required.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetExplicitPolicyRequired(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean required,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_IsPolicyMappingInhibited
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Checks whether the ProcessingParams pointed to by "params" indicate that
michael@0:  *  policyMapping is inhibited and stores the Boolean result at "pInhibited".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams used to determine whether or not policy
michael@0:  *      mappings are inhibited. Must be non-NULL.
michael@0:  *  "pInhibited"
michael@0:  *      Address where Boolean will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_IsPolicyMappingInhibited(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean *pInhibited,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ProcessingParams_SetPolicyMappingInhibited
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Specifies in the ProcessingParams pointed to by "params" whether policy
michael@0:  *  mapping is inhibited using the Boolean value of "inhibited".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "params"
michael@0:  *      Address of ProcessingParams to be set. Must be non-NULL.
michael@0:  *  "inhibited"
michael@0:  *      Boolean value indicating whether policy mapping is to be inhibited.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ProcessingParams_SetPolicyMappingInhibited(
michael@0:         PKIX_ProcessingParams *params,
michael@0:         PKIX_Boolean inhibited,
michael@0:         void *plContext);
michael@0: 
michael@0: 
michael@0: /* PKIX_ValidateParams
michael@0:  *
michael@0:  * PKIX_ValidateParams consists of a ProcessingParams object as well as the
michael@0:  * List of Certs (certChain) that the caller is trying to validate.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ValidateParams_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new ValidateParams object and stores it at "pParams".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "procParams"
michael@0:  *      Address of ProcessingParams to be used. Must be non-NULL.
michael@0:  *  "chain"
michael@0:  *      Address of List of Certs (certChain) to be validated. Must be non-NULL.
michael@0:  *  "pParams"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ValidateParams_Create(
michael@0:         PKIX_ProcessingParams *procParams,
michael@0:         PKIX_List *chain,
michael@0:         PKIX_ValidateParams **pParams,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ValidateParams_GetProcessingParams
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the ProcessingParams that represent the basic
michael@0:  *  certificate processing parameters used during chain validation and chain
michael@0:  *  building from the ValidateParams pointed to by "valParams" and stores it
michael@0:  *  at "pProcParams". If the function succeeds, the pointer to the
michael@0:  *  ProcessingParams is guaranteed to be non-NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "valParams"
michael@0:  *      Address of ValidateParams whose ProcessingParams are to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pProcParams"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ValidateParams_GetProcessingParams(
michael@0:         PKIX_ValidateParams *valParams,
michael@0:         PKIX_ProcessingParams **pProcParams,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ValidateParams_GetCertChain
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the List of Certs (certChain) that is set in the
michael@0:  *  ValidateParams pointed to by "valParams" and stores it at "pChain". If the
michael@0:  *  function succeeds, the pointer to the CertChain is guaranteed to be
michael@0:  *  non-NULL.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "valParams"
michael@0:  *      Address of ValidateParams whose CertChain is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pChain"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ValidateParams_GetCertChain(
michael@0:         PKIX_ValidateParams *valParams,
michael@0:         PKIX_List **pChain,
michael@0:         void *plContext);
michael@0: 
michael@0: /* PKIX_TrustAnchor
michael@0:  *
michael@0:  * A PKIX_TrustAnchor represents a trusted entity and can be specified using a
michael@0:  * self-signed certificate or using the trusted CA's name and public key. In
michael@0:  * order to limit the trust in the trusted entity, name constraints can also
michael@0:  * be imposed on the trust anchor.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_CreateWithCert
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new TrustAnchor object using the Cert pointed to by "cert" as
michael@0:  *  the trusted certificate and stores it at "pAnchor". Once created, a
michael@0:  *  TrustAnchor is immutable.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "cert"
michael@0:  *      Address of Cert to use as trusted certificate. Must be non-NULL.
michael@0:  *  "pAnchor"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_CreateWithCert(
michael@0:         PKIX_PL_Cert *cert,
michael@0:         PKIX_TrustAnchor **pAnchor,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_CreateWithNameKeyPair
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new TrustAnchor object using the X500Name pointed to by "name",
michael@0:  *  and the PublicKey pointed to by "pubKey" and stores it at "pAnchor". The
michael@0:  *  CertNameConstraints pointed to by "nameConstraints" (if any) are used to
michael@0:  *  limit the trust placed in this trust anchor. To indicate that name
michael@0:  *  constraints don't apply, set "nameConstraints" to NULL. Once created, a
michael@0:  *  TrustAnchor is immutable.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "name"
michael@0:  *      Address of X500Name to use as name of trusted CA. Must be non-NULL.
michael@0:  *  "pubKey"
michael@0:  *      Address of PublicKey to use as trusted public key. Must be non-NULL.
michael@0:  *  "nameConstraints"
michael@0:  *      Address of CertNameConstraints to use as initial name constraints.
michael@0:  *      If NULL, no name constraints are applied.
michael@0:  *  "pAnchor"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_CreateWithNameKeyPair(
michael@0:         PKIX_PL_X500Name *name,
michael@0:         PKIX_PL_PublicKey *pubKey,
michael@0:         PKIX_PL_CertNameConstraints *nameConstraints,
michael@0:         PKIX_TrustAnchor **pAnchor,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_GetTrustedCert
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the Cert that is set in the TrustAnchor pointed to
michael@0:  *  by "anchor" and stores it at "pCert". If "anchor" does not have a Cert
michael@0:  *  set, this function stores NULL at "pCert".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "anchor"
michael@0:  *      Address of TrustAnchor whose Cert is to be stored. Must be non-NULL.
michael@0:  *  "pChain"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_GetTrustedCert(
michael@0:         PKIX_TrustAnchor *anchor,
michael@0:         PKIX_PL_Cert **pCert,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_GetCAName
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the CA's X500Name (if any) that is set in the
michael@0:  *  TrustAnchor pointed to by "anchor" and stores it at "pCAName". If "anchor"
michael@0:  *  does not have an X500Name set, this function stores NULL at "pCAName".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "anchor"
michael@0:  *      Address of TrustAnchor whose CA Name is to be stored. Must be non-NULL.
michael@0:  *  "pCAName"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_GetCAName(
michael@0:         PKIX_TrustAnchor *anchor,
michael@0:         PKIX_PL_X500Name **pCAName,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_GetCAPublicKey
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the CA's PublicKey (if any) that is set in the
michael@0:  *  TrustAnchor pointed to by "anchor" and stores it at "pPubKey". If "anchor"
michael@0:  *  does not have a PublicKey set, this function stores NULL at "pPubKey".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "anchor"
michael@0:  *      Address of TrustAnchor whose CA PublicKey is to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pPubKey"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_GetCAPublicKey(
michael@0:         PKIX_TrustAnchor *anchor,
michael@0:         PKIX_PL_PublicKey **pPubKey,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_TrustAnchor_GetNameConstraints
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a pointer to the CertNameConstraints (if any) set in the
michael@0:  *  TrustAnchor pointed to by "anchor" and stores it at "pConstraints". If
michael@0:  *  "anchor" does not have any CertNameConstraints set, this function stores
michael@0:  *  NULL at "pConstraints".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "anchor"
michael@0:  *      Address of TrustAnchor whose CertNameConstraints are to be stored.
michael@0:  *      Must be non-NULL.
michael@0:  *  "pConstraints"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a Params Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_TrustAnchor_GetNameConstraints(
michael@0:         PKIX_TrustAnchor *anchor,
michael@0:         PKIX_PL_CertNameConstraints **pNameConstraints,
michael@0:         void *plContext);
michael@0: 
michael@0: /* PKIX_ResourceLimits
michael@0:  *
michael@0:  *  A PKIX_ResourceLimits object represents the maximum resource usage that
michael@0:  *  the caller desires. The ValidateChain or BuildChain call
michael@0:  *  will not exceed these maximum limits. For example, the caller may want
michael@0:  *  a timeout value of 1 minute, meaning that if the ValidateChain or
michael@0:  *  BuildChain function is unable to finish in 1 minute, it should abort
michael@0:  *  with an Error.
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_Create
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Creates a new ResourceLimits object and stores it at "pResourceLimits".
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "pResourceLimits"
michael@0:  *      Address where object pointer will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_Create(
michael@0:         PKIX_ResourceLimits **pResourceLimits,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_GetMaxTime
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a PKIX_UInt32 (if any) representing the maximum time that is
michael@0:  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
michael@0:  *  it at "pMaxTime". This maximum time (in seconds) should not be exceeded
michael@0:  *  by the function whose ProcessingParams contain this ResourceLimits object
michael@0:  *  (typically ValidateChain or BuildChain). It essentially functions as a
michael@0:  *  time-out value and is only appropriate if blocking I/O is being used.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum time (in seconds) is
michael@0:  *      to be stored. Must be non-NULL.
michael@0:  *  "pMaxTime"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_GetMaxTime(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 *pMaxTime,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_SetMaxTime
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum time of the ResourceLimits object pointed to by
michael@0:  *  "resourceLimits" using the PKIX_UInt32 value of "maxTime". This
michael@0:  *  maximum time (in seconds) should not be exceeded by the function
michael@0:  *  whose ProcessingParams contain this ResourceLimits object
michael@0:  *  (typically ValidateChain or BuildChain). It essentially functions as a
michael@0:  *  time-out value and is only appropriate if blocking I/O is being used.
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum time (in seconds) is
michael@0:  *      to be set. Must be non-NULL.
michael@0:  *  "maxTime"
michael@0:  *      Value of PKIX_UInt32 representing the maximum time (in seconds)
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_SetMaxTime(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 maxTime,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_GetMaxFanout
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a PKIX_UInt32 (if any) representing the maximum fanout that is
michael@0:  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
michael@0:  *  it at "pMaxFanout". This maximum fanout (number of certs) should not be
michael@0:  *  exceeded by the function whose ProcessingParams contain this ResourceLimits
michael@0:  *  object (typically ValidateChain or BuildChain). If the builder encounters
michael@0:  *  more than this maximum number of certificates when searching for the next
michael@0:  *  candidate certificate, it should abort and return an error. This
michael@0:  *  parameter is only relevant for ValidateChain if it needs to internally call
michael@0:  *  BuildChain (e.g. in order to build the chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum fanout (number of certs)
michael@0:  *      is to be stored. Must be non-NULL.
michael@0:  *  "pMaxFanout"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_GetMaxFanout(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 *pMaxFanout,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_SetMaxFanout
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum fanout of the ResourceLimits object pointed to by
michael@0:  *  "resourceLimits" using the PKIX_UInt32 value of "maxFanout". This maximum
michael@0:  *  fanout (number of certs) should not be exceeded by the function whose
michael@0:  *  ProcessingParams contain this ResourceLimits object (typically ValidateChain
michael@0:  *  or BuildChain). If the builder encounters more than this maximum number of
michael@0:  *  certificates when searching for the next candidate certificate, it should
michael@0:  *  abort and return an Error. This parameter is only relevant for ValidateChain
michael@0:  *  if it needs to internally call BuildChain (e.g. in order to build the
michael@0:  *  chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum fanout (number of certs)
michael@0:  *      is to be set. Must be non-NULL.
michael@0:  *  "maxFanout"
michael@0:  *      Value of PKIX_UInt32 representing the maximum fanout (number of certs)
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_SetMaxFanout(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 maxFanout,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_GetMaxDepth
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a PKIX_UInt32 (if any) representing the maximum depth that is
michael@0:  *  set in the ResourceLimits object pointed to by "resourceLimits" and stores
michael@0:  *  it at "pMaxDepth". This maximum depth (number of certs) should not be
michael@0:  *  exceeded by the function whose ProcessingParams contain this ResourceLimits
michael@0:  *  object (typically ValidateChain or BuildChain). If the builder encounters
michael@0:  *  more than this maximum number of certificates when searching for the next
michael@0:  *  candidate certificate, it should abort and return an error. This
michael@0:  *  parameter is only relevant for ValidateChain if it needs to internally call
michael@0:  *  BuildChain (e.g. in order to build the chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum depth (number of certs)
michael@0:  *      is to be stored. Must be non-NULL.
michael@0:  *  "pMaxDepth"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_GetMaxDepth(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 *pMaxDepth,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_SetMaxDepth
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum depth of the ResourceLimits object pointed to by
michael@0:  *  "resourceLimits" using the PKIX_UInt32 value of "maxDepth". This maximum
michael@0:  *  depth (number of certs) should not be exceeded by the function whose
michael@0:  *  ProcessingParams contain this ResourceLimits object (typically ValidateChain
michael@0:  *  or BuildChain). If the builder encounters more than this maximum number of
michael@0:  *  certificates when searching for the next candidate certificate, it should
michael@0:  *  abort and return an Error. This parameter is only relevant for ValidateChain
michael@0:  *  if it needs to internally call BuildChain (e.g. in order to build the
michael@0:  *  chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum depth (number of certs)
michael@0:  *      is to be set. Must be non-NULL.
michael@0:  *  "maxDepth"
michael@0:  *      Value of PKIX_UInt32 representing the maximum depth (number of certs)
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_SetMaxDepth(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 maxDepth,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_GetMaxNumberOfCerts
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a PKIX_UInt32 (if any) representing the maximum number of traversed
michael@0:  *  certs that is set in the ResourceLimits object pointed to by "resourceLimits"
michael@0:  *  and stores it at "pMaxNumber". This maximum number of traversed certs should
michael@0:  *  not be exceeded by the function whose ProcessingParams contain this ResourceLimits
michael@0:  *  object (typically ValidateChain or BuildChain). If the builder traverses more
michael@0:  *  than this number of certs during the build process, it should abort and
michael@0:  *  return an Error. This parameter is only relevant for ValidateChain if it
michael@0:  *  needs to internally call BuildChain (e.g. in order to build the chain to a
michael@0:  *  CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum number of traversed certs
michael@0:  *      is to be stored. Must be non-NULL.
michael@0:  *  "pMaxNumber"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_GetMaxNumberOfCerts(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 *pMaxNumber,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_SetMaxNumberOfCerts
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum number of traversed certs of the ResourceLimits object
michael@0:  *  pointed to by "resourceLimits" using the PKIX_UInt32 value of "maxNumber".
michael@0:  *  This maximum number of traversed certs should not be exceeded by the function 
michael@0:  *  whose ProcessingParams contain this ResourceLimits object (typically ValidateChain
michael@0:  *  or BuildChain). If the builder traverses more than this number of certs
michael@0:  *  during the build process, it should abort and return an Error. This parameter
michael@0:  *  is only relevant for ValidateChain if it needs to internally call BuildChain
michael@0:  *  (e.g. in order to build the chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum number of traversed certs
michael@0:  *      is to be set. Must be non-NULL.
michael@0:  *  "maxNumber"
michael@0:  *      Value of PKIX_UInt32 representing the maximum number of traversed certs
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_SetMaxNumberOfCerts(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 maxNumber,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_GetMaxNumberOfCRLs
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Retrieves a PKIX_UInt32 (if any) representing the maximum number of traversed
michael@0:  *  CRLs that is set in the ResourceLimits object pointed to by "resourceLimits"
michael@0:  *  and stores it at "pMaxNumber". This maximum number of traversed CRLs should
michael@0:  *  not be exceeded by the function whose ProcessingParams contain this ResourceLimits
michael@0:  *  object (typically ValidateChain or BuildChain). If the builder traverses more
michael@0:  *  than this number of CRLs during the build process, it should abort and
michael@0:  *  return an Error. This parameter is only relevant for ValidateChain if it
michael@0:  *  needs to internally call BuildChain (e.g. in order to build the chain to a
michael@0:  *  CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum number of traversed CRLs
michael@0:  *      is to be stored. Must be non-NULL.
michael@0:  *  "pMaxNumber"
michael@0:  *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Conditionally Thread Safe
michael@0:  *      (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_GetMaxNumberOfCRLs(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 *pMaxNumber,
michael@0:         void *plContext);
michael@0: 
michael@0: /*
michael@0:  * FUNCTION: PKIX_ResourceLimits_SetMaxNumberOfCRLs
michael@0:  * DESCRIPTION:
michael@0:  *
michael@0:  *  Sets the maximum number of traversed CRLs of the ResourceLimits object
michael@0:  *  pointed to by "resourceLimits" using the PKIX_UInt32 value of "maxNumber".
michael@0:  *  This maximum number of traversed CRLs should not be exceeded by the function 
michael@0:  *  whose ProcessingParams contain this ResourceLimits object (typically ValidateChain
michael@0:  *  or BuildChain). If the builder traverses more than this number of CRLs
michael@0:  *  during the build process, it should abort and return an Error. This parameter
michael@0:  *  is only relevant for ValidateChain if it needs to internally call BuildChain
michael@0:  *  (e.g. in order to build the chain to a CRL's issuer).
michael@0:  *
michael@0:  * PARAMETERS:
michael@0:  *  "resourceLimits"
michael@0:  *      Address of ResourceLimits object whose maximum number of traversed CRLs
michael@0:  *      is to be set. Must be non-NULL.
michael@0:  *  "maxNumber"
michael@0:  *      Value of PKIX_UInt32 representing the maximum number of traversed CRLs
michael@0:  *  "plContext"
michael@0:  *      Platform-specific context pointer.
michael@0:  * THREAD SAFETY:
michael@0:  *  Not Thread Safe - assumes exclusive access to "params"
michael@0:  *  (see Thread Safety Definitions in Programmer's Guide)
michael@0:  * RETURNS:
michael@0:  *  Returns NULL if the function succeeds.
michael@0:  *  Returns a ResourceLimits Error if the function fails in a non-fatal way.
michael@0:  *  Returns a Fatal Error if the function fails in an unrecoverable way.
michael@0:  */
michael@0: PKIX_Error *
michael@0: PKIX_ResourceLimits_SetMaxNumberOfCRLs(
michael@0:         PKIX_ResourceLimits *resourceLimits,
michael@0:         PKIX_UInt32 maxNumber,
michael@0:         void *plContext);
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #endif /* _PKIX_PARAMS_H */