windows-server-2003/ds/security/cryptoapi/pki/chain/design.txt

================================================================================
Data Structures
================================================================================

Certificate Object

This is the main object for caching of trust information for a certificate.  It
contains information which will be used to build the chain context.  This data
is specified as follows:

        Certificate Object Identifier (MD5 hash of issuer and serial no.)

        Certificate Context

        Pre calculated Trust Status Bits

                CERT_TRUST_IS_SELF_SIGNED
                CERT_TRUST_IS_IN_ROOT_STORE
                CERT_TRUST_HAS_EXACT_MATCH_ISSUER

                CERT_TRUST_IS_SIGNATURE_VALID (if it is self-signed)

        Enhanced Key Usage (merged and sorted)

        Issuer Certificate Objects (list)

                CERT_TRUST_IS_SIGNATURE_VALID for each issuer
                CERT_TRUST_IS_TIME_NESTED for each issuer

                CERT_TRUST_IS_SIGNATURE_VALID for issuer simple chain
                CERT_TRUST_IS_TIME_NESTED For issuer simple chain

        Trust List Entry Objects (LRU bounded list)

        Revocation Entry Object

Construction of a Certificate Object given a certificate context is as follows:

        Certificate Object Identifier is calculated

        Certificate Context is duplicated

        If the subject name and issuer name are equal then
                CERT_TRUST_IS_SELF_SIGNED is set

        If it is in the root store then
                CERT_TRUST_IS_IN_ROOT_STORE is set

        If it has the Authority Key Identifier extension then
                CERT_TRUST_HAS_EXACT_MATCH_ISSUER is set

        Enhanced Key Usage is calculated based on extensions and properties.

        Initialize Issuer Certificate Objects list

                If !CERT_TRUST_IS_SELF_SIGNED then
                        If CERT_TRUST_HAS_EXACT_MATCH_ISSUER then
                                FindExactMatchIssuersInEngine
                                RetrieveExactMatchIssuersByUrl
                        Otherwise
                                FindNameMatchIssuersInEngine

        Trust List Entry Objects is set to NULL

        Revocation Entry Object is set to NULL

FindExactMatchIssuersInEngine

        Check Certificate Object Cache for objects which match the given issuer
        and serial no. ( certificate object identifier )

        Add them to the Issuer Certificate Objects list

        Check configured stores for certificates which have the same Issuer
        and Serial No. and for each certificate

                If not found by hash in the Certificate Object Cache then
                        Create Certificate Object
                        Add to the Certificate Object Cache
                Add to the Issuer Certificate Objects list

RetrieveExactMatchIssuersByUrl

        Retrieve the certificate using the encoded URL

        Check the Certificate Object Cache for object matching the certificate
        hash

        If not found by hash then
                Create Certificate Object
                Add to the Certificate Object Cache
                Add to Issuer Certificate Objects list

FindNameMatchIssuersInEngine

        Get the issuer name from the certificate context in the certificate
        object

        Check the Certificate Object Cache for objects whose subject name
        match the issuer name retrieved

        Add them to the Issuer Certificate Objects list

        Check configured stores for certificates whose subject name match
        the issuer name retrieved and for each certificate

                If not found by hash in the Certificate Object Cache then
                        Create Certificate Object
                        Add to the Certificate Object Cache
                Add to the Issuer Certificate Objects list

GetIssuer

        Given a set of parameters (time, usage, additional store) determine
        the best issuer certificate object from the issuer certificate object
        list

        Assign values for the various characteristics given here in order of
        importance:

        Simple Chain Signature Validity
        Single Issuer Signature Validity
        Usage
        Time Validity
        Simple Chain Time Nesting
        Single Issuer Time Nesting

        If the Issuer Certificate Objects list is NULL and
        !CERT_TRUST_IS_SELF_SIGNED then
                Initialize the Issuer Certificate Objects list from the
                additional store

        Search the list for the best issuer using a calculated quality value

Certificate Object Cache

This is an LRU maintained cache of certificate object references keyed by the
following:

        Certificate Object Identifier

        Subject Name

        Issuer Name

        Certificate Hash (MD5)

Trust List Entry Object

This object represents a certificate's entry in a trust list.  The information
contained is as follows:

        Trust List Object

        CTL Entry

Trust List Object

This object represents a CTL and wraps the CTL context.  It also caches
certificate object references which are in this CTL and have been seen by
this chain engine.  The information contained is as follows:

        Trust List Identifier

        Enhanced Key Usage

        CTL Context

        CTL Subject Certificate Objects (LRU bounded list)

        CTL Signer Certificate Object

Trust List Object Cache

This is a cache of trust list object references keyed by the following:

        Trust List Identifier

        Trust List Usage (Individual usages are separated)

The cache is initialized from the "trust" store at creation of the chain engine
and updated when the store changes.

Revocation Entry Object

This object represents a certificate's current revocation state.  The
information contained is as follows:

        Revocation List Object

        CRL Entry

Revocation List Object

This object represents a CRL and wraps the CRL context.  It also caches
certificate object references which are in this CRL and have been seen by
this chain engine.  The information contained is as follows:

        Revocation List Origin Identifier

        CRL context

        CRL Entry Certificate Objects (list)

        CRL Issuer Certificate Object

Revocation List Object Cache

This is an LRU maintained cache of revocation object references keyed by the
revocation list origin identifier

================================================================================
Algorithms
================================================================================

CertGetCertificateChain

        Find end cert in certificate object cache and if not found create a
        temporary certificate object

        Make the end certificate object the current certificate object and until
        there are no more current objects do the following:

                Add the current object to the current simple chain

                Get the issuer of the current object