Quelle  pkix_pl_pki.h   Sprache: C

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/*
 * This file defines several platform independent functions to
 * manipulate certificates and CRLs in a portable manner.
 *
 */

#ifndef _PKIX_PL_PKI_H
#define _PKIX_PL_PKI_H

#include "pkixt.h"
#include "seccomon.h"
#include "certt.h"

#ifdef __cplusplus
extern "C" {
#endif

/* General
 *
 * Please refer to the libpkix Programmer's Guide for detailed information
 * about how to use the libpkix library. Certain key warnings and notices from
 * that document are repeated here for emphasis.
 *
 * All identifiers in this file (and all public identifiers defined in
 * libpkix) begin with "PKIX_". Private identifiers only intended for use
 * within the library begin with "pkix_".
 *
 * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
 *
 * Unless otherwise noted, for all accessor (gettor) functions that return a
 * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
 * shared object. Therefore, the caller should treat this shared object as
 * read-only and should not modify this shared object. When done using the
 * shared object, the caller should release the reference to the object by
 * using the PKIX_PL_Object_DecRef function.
 *
 * While a function is executing, if its arguments (or anything referred to by
 * its arguments) are modified, free'd, or destroyed, the function's behavior
 * is undefined.
 *
 */

/*
 * Cert
 *
 * A Cert represents an X.509 certificate. It can be created using the bytes
 * of a valid ASN.1 DER encoding. Once created, a Cert is immutable. The
 * following functions include accessors (gettors) for the various components
 * of an X.509 certificate. Also included are functions to perform various
 * checks on a certificate, including name constraints, key usage, validity
 * (expiration), and signature verification.
 */

/*
 * FUNCTION: PKIX_PL_Cert_Create
 * DESCRIPTION:
 *
 *  Creates a new certificate using the bytes in the ByteArray pointed to by
 *  "byteArray" and stores it at "pCert". If the bytes are not a valid ASN.1
 *  DER encoding of a certificate, a PKIX_Error pointer is returned. Once
 *  created, a Cert is immutable.
 *
 *  Certificate  ::=  SEQUENCE  {
 *      tbsCertificate          TBSCertificate,
 *      signatureAlgorithm      AlgorithmIdentifier,
 *      signatureValue          BIT STRING  }
 *
 *  AlgorithmIdentifier  ::=  SEQUENCE  {
 *      algorithm               OBJECT IDENTIFIER,
 *      parameters              ANY DEFINED BY algorithm OPTIONAL  }
 *
 *  TBSCertificate  ::=  SEQUENCE  {
 *      version         [0]  EXPLICIT Version DEFAULT v1,
 *      serialNumber    CertificateSerialNumber,
 *      signature       AlgorithmIdentifier,
 *      issuer          Name,
 *      validity        Validity,
 *      subject         Name,
 *      subjectPublicKeyInfo SubjectPublicKeyInfo,
 *      issuerUniqueID  [1]  IMPLICIT UniqueIdentifier OPTIONAL,
 *                          -- If present, version MUST be v2 or v3
 *      subjectUniqueID [2]  IMPLICIT UniqueIdentifier OPTIONAL,
 *                              -- If present, version MUST be v2 or v3
 *      extensions      [3]  EXPLICIT Extensions OPTIONAL
 *                              -- If present, version MUST be v3
 *      }
 *
 *  Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 *
 *  CertificateSerialNumber  ::=  INTEGER
 *
 *  Validity ::= SEQUENCE {
 *      notBefore       Time,
 *      notAfter        Time }
 *
 *  Time ::= CHOICE {
 *      utcTime         UTCTime,
 *      generalTime     GeneralizedTime }
 *
 *  UniqueIdentifier  ::=  BIT STRING
 *
 *  SubjectPublicKeyInfo  ::=  SEQUENCE  {
 *      algorithm               AlgorithmIdentifier,
 *      subjectPublicKey        BIT STRING  }
 *
 *  Extensions  ::=  SEQUENCE SIZE (1..MAX) OF Extension
 *
 *  Extension  ::=  SEQUENCE  {
 *      extnID          OBJECT IDENTIFIER,
 *      critical        BOOLEAN DEFAULT FALSE,
 *      extnValue       OCTET STRING  }
 *
 * PARAMETERS:
 *  "byteArray"
 *      Address of ByteArray representing the CERT's DER encoding.
 *      Must be non-NULL.
 *  "pCert"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_Create(
        PKIX_PL_ByteArray *byteArray,
        PKIX_PL_Cert **pCert,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_CreateFromCERTCertificate
 * DESCRIPTION:
 *
 * Creates a new certificate using passed in CERTCertificate object.
 *
 * PARAMETERS:
 *  "nssCert"
 *      The object that will be used to create new PKIX_PL_Cert.
 *  "pCert"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_CreateFromCERTCertificate(
        const CERTCertificate *nssCert,
        PKIX_PL_Cert **pCert,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetCERTCertificate
 * DESCRIPTION:
 *
 * Returns underlying CERTCertificate structure. Return CERTCertificate
 * object is duplicated and should be destroyed by caller.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of PKIX_PL_Cert. Must be non-NULL.
 *  "pCert"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetCERTCertificate(
        PKIX_PL_Cert *cert,
        CERTCertificate **pnssCert, 
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetVersion
 * DESCRIPTION:
 *
 *  Retrieves the version of the Cert pointed to by "cert" and stores it at
 *  "pVersion". The version number will either be 0, 1, or 2 (corresponding to
 *  v1, v2, or v3, respectively).
 *
 *  Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose version is to be stored. Must be non-NULL.
 *  "pVersion"
 *      Address where PKIX_UInt32 will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetVersion(
        PKIX_PL_Cert *cert,
        PKIX_UInt32 *pVersion,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSerialNumber
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the BigInt that represents the serial number of the
 *  Cert pointed to by "cert" and stores it at "pSerialNumber".
 *
 *  CertificateSerialNumber  ::=  INTEGER
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose serial number is to be stored. Must be non-NULL.
 *  "pSerial"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSerialNumber(
        PKIX_PL_Cert *cert,
        PKIX_PL_BigInt **pSerial,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetIssuer
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the X500Name that represents the issuer DN of the
 *  Cert pointed to by "cert" and stores it at "pIssuer".
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose issuer is to be stored. Must be non-NULL.
 *  "pIssuer"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetIssuer(
        PKIX_PL_Cert *cert,
        PKIX_PL_X500Name **pIssuer,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSubject
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the X500Name that represents the subject DN of the
 *  Cert pointed to by "cert" and stores it at "pSubject". If the Cert does not
 *  have a subject DN, this function stores NULL at "pSubject".
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject is to be stored. Must be non-NULL.
 *  "pSubject"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubject(
        PKIX_PL_Cert *cert,
        PKIX_PL_X500Name **pSubject,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSubjectPublicKeyAlgId
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the OID that represents the subject public key
 *  algorithm of the Cert pointed to by "cert" and stores it at
 *  "pSubjKeyAlgId".
 *
 *  SubjectPublicKeyInfo  ::=  SEQUENCE  {
 *      algorithm               AlgorithmIdentifier,
 *      subjectPublicKey        BIT STRING  }
 *
 *  AlgorithmIdentifier  ::=  SEQUENCE  {
 *      algorithm               OBJECT IDENTIFIER,
 *      parameters              ANY DEFINED BY algorithm OPTIONAL  }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject public key algorithm OID is to be stored.
 *      Must be non-NULL.
 *  "pSubjKeyAlgId"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubjectPublicKeyAlgId(
        PKIX_PL_Cert *cert,
        PKIX_PL_OID **pSubjKeyAlgId,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSubjectPublicKey
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the PublicKey that represents the subject public key
 *  of the Cert pointed to by "cert" and stores it at "pPublicKey".
 *
 *  SubjectPublicKeyInfo  ::=  SEQUENCE  {
 *      algorithm               AlgorithmIdentifier,
 *      subjectPublicKey        BIT STRING  }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject public key is to be stored.
 *      Must be non-NULL.
 *  "pPublicKey"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubjectPublicKey(
        PKIX_PL_Cert *cert,
        PKIX_PL_PublicKey **pPublicKey,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_PublicKey_NeedsDSAParameters
 * DESCRIPTION:
 *
 * Determines if the PublicKey pointed to by "pubKey" is a DSA Key with null
 * parameters and stores the result at "pNeedsParams". 
 *
 * PARAMETERS:
 *  "pubKey"
 *      Address of the Public Key of interest. Must be non-NULL.
 *  "pNeedsParams"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a PublicKey Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_PublicKey_NeedsDSAParameters(
        PKIX_PL_PublicKey *pubKey,
        PKIX_Boolean *pNeedsParams,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_PublicKey_MakeInheritedDSAPublicKey
 * DESCRIPTION:
 *
 * This function is used for DSA key parameter inheritance, which allows a
 * first DSA key with omitted parameters (pointed to by "firstKey") to inherit
 * the PQG parameters of a second DSA key that does have parameters. (pointed
 * to by "secondKey"). Once created, a PublicKey is immutable.
 *
 * Specifically, the algorithm used by the function is:
 *
 * If the first PublicKey is not a DSA public key with omitted parameters,
 *      the function stores NULL at "pResultKey". (No Error is returned)
 * Else if the second PublicKey is not a DSA public key with non-NULL,
 *      parameters, the function returns an Error.
 * Else
 *      the function creates a third PublicKey with a "Y" value from the
 *      first PublicKey and the DSA parameters from the second PublicKey,
 *      and stores it at "pResultKey".
 *
 * PARAMETERS:
 *  "firstKey"
 *      Address of a Public Key that needs to inherit DSA parameters.
 *      Must be non-NULL.
 *  "secondKey"
 *      Address of a Public Key that has DSA parameters that will be inherited
 *      by "firstKey". Must be non-NULL.
 *  "pResultKey"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a PublicKey Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_PublicKey_MakeInheritedDSAPublicKey(
        PKIX_PL_PublicKey *firstKey,
        PKIX_PL_PublicKey *secondKey,
        PKIX_PL_PublicKey **pResultKey,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetCriticalExtensionOIDs
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the List of OIDs (each OID corresponding to a
 *  critical extension of the Cert pointed to by "cert") and stores it at
 *  "pExtensions". If "cert" does not have any critical extensions, this
 *  function stores an empty List at "pExtensions".
 *
 *  Note that the List returned by this function is immutable.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose critical extension OIDs are to be stored.
 *      Must be non-NULL.
 *  "pExtensions"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetCriticalExtensionOIDs(
        PKIX_PL_Cert *cert,
        PKIX_List **pExtensions,  /* list of PKIX_PL_OID */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetAuthorityKeyIdentifier
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a ByteArray representing the authority key
 *  identifier extension of the Cert pointed to by "cert" and stores it at
 *  "pAuthKeyId".
 *
 *  Note that this function only retrieves the keyIdentifier component
 *  (OCTET STRING) of the AuthorityKeyIdentifier extension, when present.
 *
 *  If "cert" does not have an AuthorityKeyIdentifier extension or if the
 *  keyIdentifier component of the AuthorityKeyIdentifier extension is not
 *  present, this function stores NULL at "pAuthKeyId".
 *
 *  AuthorityKeyIdentifier ::= SEQUENCE {
 *      keyIdentifier                   [0] KeyIdentifier           OPTIONAL,
 *      authorityCertIssuer             [1] GeneralNames            OPTIONAL,
 *      authorityCertSerialNumber       [2] CertificateSerialNumber OPTIONAL  }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose authority key identifier is to be stored.
 *      Must be non-NULL.
 *  "pAuthKeyId"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetAuthorityKeyIdentifier(
        PKIX_PL_Cert *cert,
        PKIX_PL_ByteArray **pAuthKeyId,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSubjectKeyIdentifier
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a ByteArray representing the subject key identifier
 *  extension of the Cert pointed to by "cert" and stores it at "pSubjKeyId".
 *  If "cert" does not have a SubjectKeyIdentifier extension, this function
 *  stores NULL at "pSubjKeyId".
 *
 *  SubjectKeyIdentifier ::= KeyIdentifier
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject key identifier is to be stored.
 *      Must be non-NULL.
 *  "pSubjKeyId"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubjectKeyIdentifier(
        PKIX_PL_Cert *cert,
        PKIX_PL_ByteArray **pSubjKeyId,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetSubjectAltNames
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the List of GeneralNames (each GeneralName
 *  representing a subject alternative name found in the subject alternative
 *  names extension of the Cert pointed to by "cert") and stores it at
 *  "pSubjectAltNames". If "cert" does not have a SubjectAlternativeNames
 *  extension, this function stores NULL at "pSubjectAltNames".
 *
 *  Note that the List returned by this function is immutable.
 *
 *  SubjectAltName ::= GeneralNames
 *
 *  GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName
 *
 *  GeneralName ::= CHOICE {
 *      otherName                       [0]     OtherName,
 *      rfc822Name                      [1]     IA5String,
 *      dNSName                         [2]     IA5String,
 *      x400Address                     [3]     ORAddress,
 *      directoryName                   [4]     Name,
 *      ediPartyName                    [5]     EDIPartyName,
 *      uniformResourceIdentifier       [6]     IA5String,
 *      iPAddress                       [7]     OCTET STRING,
 *      registeredID                    [8]     OBJECT IDENTIFIER }
 *
 *  OtherName ::= SEQUENCE {
 *      type-id                         OBJECT IDENTIFIER,
 *      value                           [0] EXPLICIT ANY DEFINED BY type-id }
 *
 *  EDIPartyName ::= SEQUENCE {
 *      nameAssigner                    [0]     DirectoryString OPTIONAL,
 *      partyName                       [1]     DirectoryString }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subjectAltNames are to be stored.
 *      Must be non-NULL.
 *  "pSubjectAltNames"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubjectAltNames(
        PKIX_PL_Cert *cert,
        PKIX_List **pSubjectAltNames,  /* list of PKIX_PL_GeneralName */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetAllSubjectNames
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the List of GeneralNames (each GeneralName
 *  representing a subject DN or a subject alternative name found in the
 *  subject alternative names extension of the Cert pointed to by "cert") and
 *  stores it at "pAllSubjectNames".If the Subject DN of "cert" is empty and
 *  it does not have a SubjectAlternativeNames extension, this function stores
 *  NULL at "pAllSubjectNames".
 *
 *  Note that the List returned by this function is immutable.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject DN and subjectAltNames are to be stored.
 *      Must be non-NULL.
 *  "pAllSubjectNames"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetAllSubjectNames(
        PKIX_PL_Cert *cert,
        PKIX_List **pAllSubjectNames,  /* list of PKIX_PL_GeneralName */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetExtendedKeyUsage
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a List of OIDs (each OID corresponding to an
 *  extended key usage of the Cert pointed to by "cert") and stores it at
 *  "pKeyUsage". If "cert" does not have an extended key usage extension, this
 *  function stores a NULL at "pKeyUsage".
 *
 *  Note that the List returned by this function is immutable.
 *
 *  ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId
 *
 *  KeyPurposeId ::= OBJECT IDENTIFIER
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose extended key usage OIDs are to be stored.
 *      Must be non-NULL.
 *  "pKeyUsage"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetExtendedKeyUsage(
        PKIX_PL_Cert *cert,
        PKIX_List **pKeyUsage,  /* list of PKIX_PL_OID */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetNameConstraints
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a CertNameConstraints object representing the name
 *  constraints extension of the Cert pointed to by "cert" and stores it at
 *  "pNameConstraints".
 *
 *  If "cert" does not have a name constraints extension, this function stores
 *  NULL at "pNameConstraints".
 *
 *  NameConstraints ::= SEQUENCE {
 *      permittedSubtrees       [0]     GeneralSubtrees OPTIONAL,
 *      excludedSubtrees        [1]     GeneralSubtrees OPTIONAL }
 *
 *  GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree
 *
 *  GeneralSubtree ::= SEQUENCE {
 *      base                    GeneralName,
 *      minimum         [0]     BaseDistance DEFAULT 0,
 *      maximum         [1]     BaseDistance OPTIONAL }
 *
 *  BaseDistance ::= INTEGER (0..MAX)
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose name constraints extension is to be stored.
 *      Must be non-NULL.
 *  "pNameConstraints"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetNameConstraints(
        PKIX_PL_Cert *cert,
        PKIX_PL_CertNameConstraints **pNameConstraints,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetBasicConstraints
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a CertBasicConstraints object representing the basic
 *  constraints extension of the Cert pointed to by "cert" and stores it at
 *  "pBasicConstraints".
 *
 *  If "cert" does not have a basic constraints extension, this function stores
 *  NULL at "pBasicConstraints". Once created, a CertBasicConstraints object
 *  is immutable.
 *
 *  BasicConstraints ::= SEQUENCE {
 *      cA                      BOOLEAN DEFAULT FALSE,
 *      pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose basic constraints extension is to be stored.
 *      Must be non-NULL.
 *  "pBasicConstraints"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetBasicConstraints(
        PKIX_PL_Cert *cert,
        PKIX_PL_CertBasicConstraints **pBasicConstraints,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_BasicConstraints_GetCAFlag
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a Boolean value representing the cA Flag component
 *  of the CertBasicConstraints object pointed to by "basicConstraints" and
 *  stores it at "pResult".
 *
 *  BasicConstraints ::= SEQUENCE {
 *      cA                      BOOLEAN DEFAULT FALSE,
 *      pathLenConstraint       INTEGER (0..MAX) OPTIONAL }
 *
 * PARAMETERS:
 *  "basicConstraints"
 *      Address of CertBasicConstraints whose cA Flag is to be stored.
 *      Must be non-NULL.
 *  "pResult"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_BasicConstraints_GetCAFlag(
        PKIX_PL_CertBasicConstraints *basicConstraints,
        PKIX_Boolean *pResult,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_BasicConstraints_GetPathLenConstraint
 * DESCRIPTION:
 *
 *  Retrieves a pointer to an integer value representing the pathLenConstraint
 *  component of the CertBasicConstraints object pointed to by
 *  "basicConstraints" and stores it at "pPathLenConstraint". If the
 *  pathLenConstraint component is not present, this function stores -1 at
 *  "pPathLenConstraint".
 *
 * PARAMETERS:
 *  "basicConstraints"
 *      Address of CertBasicConstraints whose pathLen is to be stored.
 *      Must be non-NULL.
 *  "pPathLenConstraint"
 *      Address where PKIX_Int32 will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_BasicConstraints_GetPathLenConstraint(
        PKIX_PL_CertBasicConstraints *basicConstraints,
        PKIX_Int32 *pPathLenConstraint,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetPolicyInformation
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a List of CertPolicyInfos found in the certificate
 *  policies extension of the Cert pointed to by "cert" and stores it at
 *  "pPolicyInfo". If "cert" does not have a certificate policies extension,
 *  this function stores NULL at "pPolicyInfo". Once created, a CertPolicyInfo
 *  object is immutable.
 *
 *  Note that the List returned by this function is immutable.
 *
 *  certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation
 *
 *  PolicyInformation ::= SEQUENCE {
 *      policyIdentifier   CertPolicyId,
 *      policyQualifiers   SEQUENCE SIZE (1..MAX) OF
 *                              PolicyQualifierInfo OPTIONAL }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose CertPolicyInfos are to be stored.
 *      Must be non-NULL.
 *  "pPolicyInfo"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetPolicyInformation(
        PKIX_PL_Cert *cert,
        PKIX_List **pPolicyInfo, /* list of PKIX_PL_CertPolicyInfo */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_CertPolicyInfo_GetPolicyId
 * DESCRIPTION:
 *
 *  Retrieves a pointer to an OID representing the policyIdentifier of the
 *  CertPolicyInfo pointed to by "policyInfo" and stores it at "pCertPolicyId".
 *
 *  certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation
 *
 *  PolicyInformation ::= SEQUENCE {
 *      policyIdentifier   CertPolicyId,
 *      policyQualifiers   SEQUENCE SIZE (1..MAX) OF
 *                              PolicyQualifierInfo OPTIONAL }
 *
 *  CertPolicyId ::= OBJECT IDENTIFIER
 *
 * PARAMETERS:
 *  "policyInfo"
 *      Address of CertPolicyInfo whose policy identifier is to be stored.
 *      Must be non-NULL.
 *  "pCertPolicyId"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_CertPolicyInfo_GetPolicyId(
        PKIX_PL_CertPolicyInfo *policyInfo,
        PKIX_PL_OID **pCertPolicyId,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_CertPolicyInfo_GetPolQualifiers
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a List of the CertPolicyQualifiers representing
 *  the policyQualifiers of the CertPolicyInfo pointed to by "policyInfo" and
 *  stores it at "pPolicyQualifiers". If "policyInfo" does not have any
 *  policyQualifiers, this function stores NULL at "pPolicyQualifiers". Once
 *  created, a CertPolicyQualifier is immutable.
 *
 *  Note that the List returned by this function is immutable.
 *
 *  certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation
 *
 *  PolicyInformation ::= SEQUENCE {
 *      policyIdentifier   CertPolicyId,
 *      policyQualifiers   SEQUENCE SIZE (1..MAX) OF
 *                              PolicyQualifierInfo OPTIONAL }
 *
 *  PolicyQualifierInfo ::= SEQUENCE {
 *      policyQualifierId  PolicyQualifierId,
 *      qualifier       ANY DEFINED BY policyQualifierId }
 *
 * PARAMETERS:
 *  "policyInfo"
 *      Address of CertPolicyInfo whose policy qualifiers List is to be stored.
 *      Must be non-NULL.
 *  "pPolicyQualifiers"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_CertPolicyInfo_GetPolQualifiers(
        PKIX_PL_CertPolicyInfo *policyInfo,
        PKIX_List **pPolicyQualifiers, /* list of PKIX_PL_CertPolicyQualifier */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_PolicyQualifier_GetPolicyQualifierId
 * DESCRIPTION:
 *
 *  Retrieves a pointer to an OID representing the policyQualifierId of the
 *  CertPolicyQualifier pointed to by "policyQualifier" and stores it at
 *  "pPolicyQualifierId".
 *
 *  PolicyQualifierInfo ::= SEQUENCE {
 *      policyQualifierId       PolicyQualifierId,
 *      qualifier               ANY DEFINED BY policyQualifierId }
 *
 *  PolicyQualifierId ::=
 *      OBJECT IDENTIFIER ( id-qt-cps | id-qt-unotice )
 *
 * PARAMETERS:
 *  "policyQualifier"
 *      Address of CertPolQualifier whose policyQualifierId is to be stored.
 *      Must be non-NULL.
 *  "pPolicyQualifierId"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_PolicyQualifier_GetPolicyQualifierId(
        PKIX_PL_CertPolicyQualifier *policyQualifier,
        PKIX_PL_OID **pPolicyQualifierId,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_PolicyQualifier_GetQualifier
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a ByteArray representing the qualifier of the
 *  CertPolicyQualifier pointed to by "policyQualifier" and stores it at
 *  "pQualifier".
 *
 *  PolicyQualifierInfo ::= SEQUENCE {
 *      policyQualifierId       PolicyQualifierId,
 *      qualifier               ANY DEFINED BY policyQualifierId }
 *
 * PARAMETERS:
 *  "policyQualifier"
 *      Address of CertPolicyQualifier whose qualifier is to be stored.
 *      Must be non-NULL.
 *  "pQualifier"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_PolicyQualifier_GetQualifier(
        PKIX_PL_CertPolicyQualifier *policyQualifier,
        PKIX_PL_ByteArray **pQualifier,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetPolicyMappings
 * DESCRIPTION:
 *
 *  Retrieves a pointer to a List of CertPolicyMaps found in the policy
 *  mappings extension of the Cert pointed to by "cert" and stores it at
 *  "pPolicyMappings". If "cert" does not have a policy mappings extension,
 *  this function stores NULL at "pPolicyMappings". Once created, a
 *  CertPolicyMap is immutable.
 *
 *  Note that the List returned by this function is immutable.
 *
 *  PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE {
 *      issuerDomainPolicy      CertPolicyId,
 *      subjectDomainPolicy     CertPolicyId }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose CertPolicyMaps are to be stored.
 *      Must be non-NULL.
 *  "pPolicyMappings"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetPolicyMappings(
        PKIX_PL_Cert *cert,
        PKIX_List **pPolicyMappings, /* list of PKIX_PL_CertPolicyMap */
        void *plContext);

/*
 * FUNCTION: PKIX_PL_CertPolicyMap_GetIssuerDomainPolicy
 * DESCRIPTION:
 *
 *  Retrieves a pointer to an OID representing the issuerDomainPolicy of the
 *  CertPolicyMap pointed to by "policyMapping" and stores it at
 *  "pIssuerDomainPolicy".
 *
 *  PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE {
 *      issuerDomainPolicy      CertPolicyId,
 *      subjectDomainPolicy     CertPolicyId }
 *
 * PARAMETERS:
 *  "policyMapping"
 *      Address of CertPolicyMap whose issuerDomainPolicy is to be stored.
 *      Must be non-NULL.
 *  "pIssuerDomainPolicy"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_CertPolicyMap_GetIssuerDomainPolicy(
        PKIX_PL_CertPolicyMap *policyMapping,
        PKIX_PL_OID **pIssuerDomainPolicy,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_CertPolicyMap_GetSubjectDomainPolicy
 * DESCRIPTION:
 *
 *  Retrieves a pointer to an OID representing the subjectDomainPolicy of the
 *  CertPolicyMap pointed to by "policyMapping" and stores it at
 *  "pSubjectDomainPolicy".
 *
 *  PolicyMappings ::= SEQUENCE SIZE (1..MAX) OF SEQUENCE {
 *      issuerDomainPolicy      CertPolicyId,
 *      subjectDomainPolicy     CertPolicyId }
 *
 * PARAMETERS:
 *  "policyMapping"
 *      Address of CertPolicyMap whose subjectDomainPolicy is to be stored.
 *      Must be non-NULL.
 *  "pSubjectDomainPolicy"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_CertPolicyMap_GetSubjectDomainPolicy(
        PKIX_PL_CertPolicyMap *policyMapping,
        PKIX_PL_OID **pSubjectDomainPolicy,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetRequireExplicitPolicy
 * DESCRIPTION:
 *
 *  Retrieves the requireExplicitPolicy value of the policy constraints
 *  extension of the Cert pointed to by "cert" and stores it at "pSkipCerts".
 *  If "cert" does not have a policy constraints extension or the
 *  requireExplicitPolicy component is not populated, this function stores -1
 *  at "pSkipCerts".
 *
 *  PolicyConstraints ::= SEQUENCE {
 *      requireExplicitPolicy   [0] SkipCerts OPTIONAL,
 *      inhibitPolicyMapping    [1] SkipCerts OPTIONAL }
 *
 *  SkipCerts ::= INTEGER (0..MAX)
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose requireExplicitPolicy value is to be stored.
 *      Must be non-NULL.
 *  "pSkipCerts"
 *      Address where PKIX_Int32 will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetRequireExplicitPolicy(
        PKIX_PL_Cert *cert,
        PKIX_Int32 *pSkipCerts,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetPolicyMappingInhibited
 * DESCRIPTION:
 *
 *  Retrieves the inhibitPolicyMapping value of the policy constraints
 *  extension of the Cert pointed to by "cert" and stores it at "pSkipCerts".
 *  If "cert" does not have a policy constraints extension or the
 *  inhibitPolicyMapping component is not populated, this function stores -1
 *  at "pSkipCerts".
 *
 *  PolicyConstraints ::= SEQUENCE {
 *      requireExplicitPolicy   [0] SkipCerts OPTIONAL,
 *      inhibitPolicyMapping    [1] SkipCerts OPTIONAL }
 *
 *  SkipCerts ::= INTEGER (0..MAX)
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose requireExplicitPolicy value is to be stored.
 *      Must be non-NULL.
 *  "pSkipCerts"
 *      Address where PKIX_Int32 will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetPolicyMappingInhibited(
        PKIX_PL_Cert *cert,
        PKIX_Int32 *pSkipCerts,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetInhibitAnyPolicy
 * DESCRIPTION:
 *
 *  Retrieves the value of the inhibit any-policy extension of the Cert
 *  pointed to by "cert" and stores it at "pSkipCerts". If "cert" does not have
 *  an inhibit any-policy extension, this function stores -1 at "pSkipCerts".
 *
 *  InhibitAnyPolicy ::= SkipCerts
 *
 *  SkipCerts ::= INTEGER (0..MAX)
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose inhibit any-policy extensions value is to be
 *      stored. Must be non-NULL.
 *  "pSkipCerts"
 *      Address where PKIX_Int32 will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetInhibitAnyPolicy(
        PKIX_PL_Cert *cert,
        PKIX_Int32 *pSkipCerts,
        void *plContext);

/* policy processing functions */

/*
 * FUNCTION: PKIX_PL_Cert_AreCertPoliciesCritical
 * DESCRIPTION:
 *
 *  Checks whether the certificate policies extension of the Cert pointed to
 *  by "cert" is critical and stores the Boolean result at "pCritical". If
 *  "cert" does not have a certificate policies extension, this function
 *  stores NULL at "pCritical".
 *
 *  XXX what distinguishes NULL from PKIX_FALSE?
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose certificate policies extension's criticality is
 *      to be determined. Must be non-NULL.
 *  "pCritical"
 *      Address where PKIX_Boolean will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_AreCertPoliciesCritical(
        PKIX_PL_Cert *cert,
        PKIX_Boolean *pCritical,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_CheckNameConstraints
 * DESCRIPTION:
 *
 *  Checks whether the subject distinguished name and subject alternative names
 *  of the Cert pointed to by "cert" satisfy the CertNameConstraints pointed
 *  to by "nameConstraints". If the CertNameConstraints are not satisfied, a
 *  PKIX_Error pointer is returned. If "nameConstraints" is NULL, the function
 *  does nothing.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose subject names are to be checked.
 *      Must be non-NULL.
 *  "nameConstraints"
 *      Address of CertNameConstraints that need to be satisfied.
 *  "treatCommonNameAsDNSName"
 *      PKIX_TRUE if the subject common name should be considered a dNSName
 *      when evaluating name constraints.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_CheckNameConstraints(
        PKIX_PL_Cert *cert,
        PKIX_PL_CertNameConstraints *nameConstraints,
        PKIX_Boolean treatCommonNameAsDNSName,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_MergeNameConstraints
 * DESCRIPTION:
 *
 *  Merges the CertNameConstraints pointed to by "firstNC" and the
 *  CertNameConstraints pointed to by "secondNC" and stores the merged
 *  CertNameConstraints at "pResultNC". If "secondNC" is NULL, the
 *  CertNameConstraints pointed to by "firstNC" is stored at "pResultNC".
 *
 *  Once created, a CertNameConstraints object is immutable.
 *
 * PARAMETERS:
 *  "firstNC"
 *      Address of first CertNameConstraints to be merged. Must be non-NULL.
 *  "secondNC"
 *      Address of second CertNameConstraints to be merged
 *  "pResultNC"
 *      Address where object pointer will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_MergeNameConstraints(
        PKIX_PL_CertNameConstraints *firstNC,
        PKIX_PL_CertNameConstraints *secondNC,
        PKIX_PL_CertNameConstraints **pResultNC,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_VerifyKeyUsage
 * DESCRIPTION:
 *
 *  Verifies that the keyUsage bit(s) specified by "keyUsage" appear in the
 *  keyUsage extension of the Cert pointed to by "cert". The keyUsage bit
 *  values specified in pkixt.h are supported, and can be bitwise or'ed if
 *  multiple bit values are to be verified. If the keyUsages do not all appear
 *  in the keyUsage extension of "cert", a PKIX_Error pointer is returned.
 *
 *  KeyUsage ::= BIT STRING {
 *      digitalSignature        (0),
 *      nonRepudiation          (1),
 *      keyEncipherment         (2),
 *      dataEncipherment        (3),
 *      keyAgreement            (4),
 *      keyCertSign             (5),
 *      cRLSign                 (6),
 *      encipherOnly            (7),
 *      decipherOnly            (8) }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose keyUsage bits are to be verified.
 *      Must be non-NULL.
 *  "keyUsage"
 *      Constant representing keyUsage bit(s) that all must appear in keyUsage
 *      extension of "cert".
 *  "plContext" - Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_VerifyKeyUsage(
        PKIX_PL_Cert *cert,
        PKIX_UInt32 keyUsage,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_VerifyCertAndKeyType
 * DESCRIPTION:
 *
 * Verifies cert and key types against certificate usage that is
 * a part of plContext(pkix_pl_nsscontext) structure. Throws an error
 * if cert or key types does not match.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose keyUsage bits are to be verified.
 *      Must be non-NULL.
 *  "isLeafCert"
 *      What type of a cert has been verified.
 *  "plContext" - Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_VerifyCertAndKeyType(
        PKIX_PL_Cert *cert,
        PKIX_Boolean isChainCert,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_CheckValidity
 * DESCRIPTION:
 *
 *  Checks whether the Cert pointed to by "cert" would be valid at the time
 *  represented by the Date pointed to by "date". If "date" is NULL, then this
 *  function checks whether the Cert would be valid at the current time. If the
 *  Cert would not be valid at the specified Date, a PKIX_Error pointer is
 *  returned.
 *
 *  Validity ::= SEQUENCE {
 *      notBefore       Time,
 *      notAfter        Time }
 *
 *  Time ::= CHOICE {
 *      utcTime         UTCTime,
 *      generalTime     GeneralizedTime }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose validity is to be checked. Must be non-NULL.
 *  "date"
 *      Address of Date at which the Cert is being checked for validity.
 *      If NULL, the current time is used for the Date.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_CheckValidity(
        PKIX_PL_Cert *cert,
        PKIX_PL_Date *date,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetValidityNotAfter
 * DESCRIPTION:
 *
 *  Retrieves a pointer to the Date that represents the notAfter time of the
 *  Certificate pointed to by "cert" and stores it at "pDate".
 *
 *  Validity ::= SEQUENCE {
 *      notBefore       Time,
 *      notAfter        Time }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose validity time is to be retrieved. Must be
 *      non-NULL.
 *  "date"
 *      Address of Date at which the Cert's notAfter time is being retrieved.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetValidityNotAfter(
        PKIX_PL_Cert *cert,
        PKIX_PL_Date **pDate,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_VerifySignature
 * DESCRIPTION:
 *
 *  Verifies the signature on the Cert pointed to by "cert" using the
 *  PublicKey pointed to by "pubKey". If the signature doesn't verify, an
 *  Error pointer is returned.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose signature is to be verified. Must be non-NULL.
 *  "pubKey"
 *      Address of a Public Key used to verify the signature. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_VerifySignature(
        PKIX_PL_Cert *cert,
        PKIX_PL_PublicKey *pubKey,
        void *plContext);

/* A set of flags to indicate how explicitly configured trust anchors should be
 * handled by PKIX_PL_Cert_IsCertTrusted
 */
typedef enum PKIX_PL_TrustAnchorModeEnum {
        /* Indicates trust anchors should be ignored; only the underlying
         * platform's trust settings should be used.
         */
        PKIX_PL_TrustAnchorMode_Ignore,

        /* Indicates that explicitly configured trust anchors may be considered
         * trustworthy, if present.
         * Note: If the underlying platform supports marking a certificate as
         *       explicitly untrustworthy, explicitly configured trust anchors
         *       MAY be ignored/rejected.
         */
        PKIX_PL_TrustAnchorMode_Additive,

        /* Indicates that ONLY trust anchors should be considered as
         * trustworthy.
         * Note: If the underlying platform supports marking a certificate as
         *       explicitly untrustworthy, explicitly configured trust anchors
         *       MAY be ignored/rejected.
         */
        PKIX_PL_TrustAnchorMode_Exclusive
} PKIX_PL_TrustAnchorMode;

/*
 * FUNCTION: PKIX_PL_Cert_IsCertTrusted
 * DESCRIPTION:
 *
 *  Checks the Cert specified by "cert" to determine, in a manner that depends
 *  on the underlying platform, whether it is trusted, and stores the result in
 *  "pTrusted". If a certificate is trusted it means that a chain built to that
 *  certificate, and satisfying all the usage, policy, validity, and other
 *  tests, is a valid chain and the End Entity certificate from which it was
 *  built can be trusted.
 *
 *  If the Certificate is not intrinsically trustworthy, it still might end up a
 *  component in a successful chain.
 *
 *  If the Certificate is intrinsically untrustworthy, this function will return
 *  an error. 
 *
 * PARAMETERS
 *  "cert"
 *      Address of Cert whose trustworthiness is to be determined. Must be
 *      non-NULL.
 *  "trustAnchorMode"
 *      A PKIX_PL_TrustAnchorMode that indicates how explicitly defined user
 *      trust anchors should be handled.
 *  "pTrusted"
 *      Address where the Boolean value will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CERT Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_IsCertTrusted(
        PKIX_PL_Cert *cert,
        PKIX_PL_TrustAnchorMode trustAnchorMode,
        PKIX_Boolean *pTrusted,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_IsLeafCertTrusted
 * DESCRIPTION:
 *
 *  Checks the Leaf Cert specified by "cert" to determine, in a manner that 
 *  depends on the underlying platform, whether it is trusted, and stores the 
 *  result in "pTrusted". If a certificate is trusted it means that this
 *  End Entify certificate has been marked as trusted for the requested usage,
 *  policy, validity, and other tests.
 *
 *  If the Certificate is not intrinsically trustworthy, we can still try to 
 *  build a successful chain.
 *
 *  If the Certificate is intrinsically untrustworthy, this function will return
 *  an error. 
 *
 * PARAMETERS
 *  "cert"
 *      Address of Cert whose trustworthiness is to be determined. Must be
 *      non-NULL.
 *  "pTrusted"
 *      Address where the Boolean value will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a CERT Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_IsLeafCertTrusted(
        PKIX_PL_Cert *cert,
        PKIX_Boolean *pTrusted,
        void *plContext);

/* FUNCTION: PKIX_PL_Cert_SetAsTrustAnchor */
PKIX_Error*
PKIX_PL_Cert_SetAsTrustAnchor(PKIX_PL_Cert *cert, 
                              void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetCacheFlag
 * DESCRIPTION:
 *
 *  Retrieves the value of the cache flag in "cert" and return it at address
 *  pointed by "pCacheFlag". The initila cache flag is determined by the
 *  CertStore this "cert" is fetched from. When CertStore is created, user
 *  need to specify if the data should be cached.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose cache flag is fetched. Must be non-NULL.
 *  "pCacheFlag"
 *      Address where PKIX_Boolean will be stored. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetCacheFlag(
        PKIX_PL_Cert *cert,
        PKIX_Boolean *pCacheFlag,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_SetCacheFlag
 * DESCRIPTION:
 *
 *  Set the value of the cache flag in "cert" base on the boolean value stored
 *  at "cacheFlag". This function is meant to be used by CertStore after a
 *  Cert is created.
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert where "cacheFlag" is stored. Must be non-NULL.
 *  "cacheFlag"
 *      PKIX_Boolean flag for cache flag.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_SetCacheFlag(
        PKIX_PL_Cert *cert,
        PKIX_Boolean cacheFlag,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_GetTrustCertStore
 * DESCRIPTION:
 *
 *  Retrieves the value of the CertStore in "cert" and return it at address
 *  pointed by "pCertStore".
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose CertStore is fetched. Must be non-NULL.
 *  "pTrustCertStore"
 *      Address where CertStore will be stored and returned. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetTrustCertStore(
        PKIX_PL_Cert *cert,
        PKIX_CertStore **pTrustCertStore,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_Cert_SetTrustCertStore
 * DESCRIPTION:
 *
 *  Set the value of the CertStore "certStore" in "cert".
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert where "certStore" will be stored. Must be non-NULL.
 *  "trustCertStore"
 *      Address where the CertStore is. Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_SetTrustCertStore(
        PKIX_PL_Cert *cert,
        PKIX_CertStore *trustCertStore,
        void *plContext);


/*
 * FUNCTION: PKIX_PL_Cert_GetAuthorityInfoAccess
 * DESCRIPTION:
 *
 *  Retrieves the value(s) of the Authority Information Access in "cert" and
 *  returns it in a list at address pointed by "pAuthorityInfoAccess".
 *
 *  SubjectInfoAccess ::=
 *    SEQUENCE SIZE (1..MAX) of AccessDescription
 *    AccessDescription ::= SEQUENCE {
 *        accessMethod     OBJECT IDENTIFIER,
 *        accessLocation   GeneralName
 *    }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose Authority Information Access is fetched.
 *      Must be non-NULL.
 *  "pAuthorityInfoAccess"
 *      Address where Authority InfoAccess will be stored and returned.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetAuthorityInfoAccess(
        PKIX_PL_Cert *cert,
        PKIX_List **pAiaList, /* of PKIX_PL_InfoAccess */
        void *plContext);


/*
 * FUNCTION: PKIX_PL_Cert_GetSubjectInfoAccess
 * DESCRIPTION:
 *
 *  Retrieves the value(s) of the Subject Information Access in "cert" and
 *  returns it in a list at address pointed by "pSubjectInfoAccess".
 *
 *  SubjectInfoAccess ::=
 *    SEQUENCE SIZE (1..MAX) of AccessDescription
 *    AccessDescription ::= SEQUENCE {
 *        accessMethod     OBJECT IDENTIFIER,
 *        accessLocation   GeneralName
 *    }
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose Subject Information Access is fetched.
 *      Must be non-NULL.
 *  "pSubjectInfoAccess"
 *      Address where Subject InfoAccess will be stored and returned.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetSubjectInfoAccess(
        PKIX_PL_Cert *cert,
        PKIX_List **pSiaList, /* of PKIX_PL_InfoAccess */
        void *plContext);



/*
 * FUNCTION: PKIX_PL_Cert_GetCrlDp
 * DESCRIPTION:
 *
 *  Retrieves the value(s) of the CRL Distribution Point Extension and
 *  returns it in a list at address pointed by "pDpList".
 *
 * PARAMETERS:
 *  "cert"
 *      Address of Cert whose Subject Information Access is fetched.
 *      Must be non-NULL.
 *  "pDpList"
 *      Address where CRL DP will be stored and returned.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_Cert_GetCrlDp(PKIX_PL_Cert *cert,
                      PKIX_List **pDpList,
                      void *plContext);


/*
 * InfoAccess 
 *
 * To hold Authority Information Access or Subject Information Access
 * retrieved from a Certificate.
 */

#define PKIX_INFOACCESS_OCSP          1
#define PKIX_INFOACCESS_CA_ISSUERS    2
#define PKIX_INFOACCESS_TIMESTAMPING  3
#define PKIX_INFOACCESS_CA_REPOSITORY 5

#define PKIX_INFOACCESS_LOCATION_UNKNOWN 0
#define PKIX_INFOACCESS_LOCATION_HTTP    1
#ifndef NSS_PKIX_NO_LDAP
#define PKIX_INFOACCESS_LOCATION_LDAP    2
#endif

/*
 * FUNCTION: PKIX_PL_InfoAccess_GetMethod
 * DESCRIPTION:
 *
 *  Stores the method of the Information Access from "infoAccess" and
 *  returns in "pMethod".
 *
 *  SubjectInfoAccess ::=
 *    AccessDescription ::= SEQUENCE {
 *        accessMethod     OBJECT IDENTIFIER,
 *        accessLocation   GeneralName
 *    }
 *
 * PARAMETERS:
 *  "infoAccess"
 *      Address of PKIX_PL_InfoAccess that has the access data.
 *      Must be non-NULL.
 *  "pMethod"
 *      Address where access method will be stored and returned.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
 *  Returns NULL if the function succeeds.
 *  Returns a Cert Error if the function fails in a non-fatal way.
 *  Returns a Fatal Error if the function fails in an unrecoverable way.
 */
PKIX_Error *
PKIX_PL_InfoAccess_GetMethod(
        PKIX_PL_InfoAccess *infoAccess,
        PKIX_UInt32 *pMethod,
        void *plContext);

/*
 * FUNCTION: PKIX_PL_InfoAccess_GetLocation
 * DESCRIPTION:
 *
 *  Stores the location of the Information Access from "infoAccess" and
 *  returns in "pLocation".
 *
 *  SubjectInfoAccess ::=
 *    AccessDescription ::= SEQUENCE {
 *        accessMethod     OBJECT IDENTIFIER,
 *        accessLocation   GeneralName
 *    }
 *
 * PARAMETERS:
 *  "infoAccess"
 *      Address of PKIX_PL_InfoAccess that has the access data.
 *      Must be non-NULL.
 *  "pLocation"
 *      Address where access location will be stored and returned.
 *      Must be non-NULL.
 *  "plContext"
 *      Platform-specific context pointer.
 * THREAD SAFETY:
 *  Thread Safe (see Thread Safety Definitions in Programmer's Guide)
 * RETURNS:
--> --------------------

--> maximum size reached

--> --------------------