Estendendo a funcionalidade do CertOpenStore

Ode armazenamento de certificadosé central para todas as operações de gestão de certificados. A funcionalidade da funçãoCertOpenStore pode ser estendida através do uso de uma função de provedor de armazenamento de certificados instalável (ou registrada). Para obter uma visão geral de como instalar ou registrar funções para uso com a CryptoAPI, consulte Visão geral do OID.

Observação

Os repositórios de certificados personalizados não são migrados automaticamente ao executar implantações automatizadas. Para migrar repositórios de certificados personalizados, você deve criar um manifesto para migrar os repositórios personalizados e usar a Ferramenta de Migração de Estado do Usuário do Windows (USMT).

 

CertOpenStore abre um armazenamento vazio na memória e chama a função do provedor de armazenamento (se estiver registada ou instalada) utilizando o identificador de objeto (OID) que foi passado no parâmetro lpszStoreProvider. Para obter uma lista dos tipos de provedor predefinidos fornecidos com a CryptoAPI, consulte CertOpenStore.

A função de provedor de armazenamento copia seus certificados e listas de revogação de certificados (CRLs) para o armazenamento na memória especificado pelo identificador de hCertStore passado para ele. A nova função de provedor de armazenamento pode usar qualquer uma das funções de armazenamento de certificados do CryptoAPI, como CertAddCertificateContextToStore ou CertAddSerializedElementToStore, para adicionar os seus certificados e CRLs ao armazenamento em memória. Além disso, a função store-provider opcionalmente retorna valores para todos os membros de dados da estrutura CERT_STORE_PROV_INFO. A função só precisa atualizar essa estrutura se suportar funções adicionais de retorno de chamada. Por exemplo, se o armazenamento fosse de somente leitura, o suporte de outras funções de callback provavelmente não seria necessário. Para obter detalhes e protótipos das potenciais funções de chamada de retorno, consulte Funções de chamada de retorno do fornecedor de armazenamento de certificados.

A loja TrustedPeople por usuário é restrita a lojas físicas predefinidas. Não é possível estender o repositório TrustedPeople por usuário. No entanto, você pode estender o armazenamento TrustedPeople da máquina local.

Windows XP e Windows Server 2003: O repositório TrustedPeople por usuário não está restrito a lojas físicas predefinidas.

Um dos membros de dados da estrutura CERT_STORE_PROV_INFO é a matriz rgpvStoreProvFunc . Se a função de provedor de armazenamento precisar suportar uma ou mais das funções de retorno de chamada, ela deverá fornecer ponteiros para essa matriz. Esses ponteiros devem direcionar para as funções de retorno de chamada a serem utilizadas em outras atividades relacionadas ao repositório de certificados (como fechar o repositório). A ilustração a seguir mostra o fluxo desse processo.

Como mostrado na ilustração a seguir, depois da abertura da loja, outras funções CryptoAPI (como CertCloseStore) usam a matriz de ponteiros para acessar as funções de retorno de chamada que executam a tarefa pretendida. A definição da estrutura CERT_STORE_PROV_INFO e dos protótipos das funções de retorno de chamada padrão fornecidas com a CryptoAPI são mostrados em Funções de Retorno de Chamada do Provedor de Armazenamento de Certificados.

As APIs da loja permitem que um fornecedor de armazenamento mantenha os certificados, CRLs e listas de confiança de certificados (CTLs) fora do cache da loja (por exemplo, um banco de dados externo de certificados, como o fornecido pelo Microsoft Certificate Server Database).

CertOpenStore despacha através do parâmetro pszStoreProvider para a função de provedor instalável apropriada CertDllOpenStoreProv. O provedor retorna informações no pStoreProvInfo parâmetro que aponta para uma estrutura CERT_STORE_PROV_INFO. A estrutura CERT_STORE_PROV_INFO contém um membro dwStoreProvFlags. O indicador CERT_STORE_PROV_EXTERNAL_FLAG foi adicionado para permitir que o provedor indique que os certificados, CRLs e CTLs estão fora do cache da loja.

CertDllOpenStoreProv retorna uma matriz de funções de retorno de chamada. Um provedor pode implementar as seguintes funções de retorno de chamada:

• CERT_STORE_PROV_CLOSE_FUNC
• CERT_STORE_PROV_READ_CERT_FUNC
• CERT_STORE_PROV_WRITE_CERT_FUNC
• CERT_STORE_PROV_DELETE_CERT_FUNC
• CERT_STORE_PROV_SET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_READ_CRL_FUNC
• CERT_STORE_PROV_WRITE_CRL_FUNC
• CERT_STORE_PROV_DELETE_CRL_FUNC
• CERT_STORE_PROV_SET_CRL_PROPERTY_FUNC
• CERT_STORE_PROV_READ_CTL_FUNC
• CERT_STORE_PROV_WRITE_CTL_FUNC
• CERT_STORE_PROV_DELETE_CTL_FUNC
• CERT_STORE_PROV_SET_CTL_PROPERTY_FUNC

Em chamadas para as funções de retorno de chamada WRITE_CERT, WRITE_CRL e WRITE_CTL, quando o CERT_STORE_PROV_WRITE_ADD_FLAG é definido, os 16 bits superiores do parâmetro dwFlags contêm o valor dwAddDisposition. Para oferecer suporte a repositórios externos, um provedor pode implementar as seguintes funções de retorno de chamada:

• CERT_STORE_PROV_FIND_CERT_FUNC
• CERT_STORE_PROV_FREE_FIND_CERT_FUNC
• CERT_STORE_PROV_GET_CERT_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CRL_FUNC
• CERT_STORE_PROV_FREE_FIND_CRL_FUNC
• [Assuming no translation is needed] CERT_STORE_PROV_GET_CRL_PROPERTY_FUNC
• CERT_STORE_PROV_FIND_CTL_FUNC
• CERT_STORE_PROV_FREE_FIND_CTL_FUNC
• CERT_STORE_PROV_GET_CTL_PROPERTY_FUNC

As funções de retorno de chamada de certificado têm as seguintes assinaturas:

typedef struct _CERT_STORE_PROV_FIND_INFO {
    DWORD               cbSize;
    DWORD               dwMsgAndCertEncodingType;
    DWORD               dwFindFlags;
    DWORD               dwFindType;
    const void          *pvFindPara;
} CERT_STORE_PROV_FIND_INFO, *PCERT_STORE_PROV_FIND_INFO;
typedef const CERT_STORE_PROV_FIND_INFO CCERT_STORE_PROV_FIND_INFO,
    *PCCERT_STORE_PROV_FIND_INFO;

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_STORE_PROV_FIND_INFO pFindInfo,
        IN PCCERT_CONTEXT pPrevCertContext,
        IN DWORD dwFlags,
        IN OUT void **ppvStoreProvFindInfo,
        OUT PCCERT_CONTEXT *ppProvCertContext
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_FREE_FIND_CERT)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN void *pvStoreProvFindInfo,
        IN DWORD dwFlags
        );

typedef BOOL (WINAPI *PFN_CERT_STORE_PROV_GET_CERT_PROPERTY)(
        IN HCERTSTOREPROV hStoreProv,
        IN PCCERT_CONTEXT pCertContext,
        IN DWORD dwPropId,
        IN DWORD dwFlags,
        OUT void *pvData,
        IN OUT DWORD *pcbData
        );

As assinaturas para as funções de retorno de chamada CRL e CTL são idênticas às acima, com o ponteiro para o CERT_CONTEXT substituído por um ponteiro para um CRL_CONTEXT ou CTL_CONTEXT.

O callback FIND_CERT é chamado quando as APIs de armazenamento enumeram, procuram ou adicionam certificados. pPrevCertContext e ppvStoreProvFindInfo são definidos como NULL para iniciar um novo FIND. O ppvStoreProvFindInfo retornado é devolvido na próxima pesquisa, momento em que pode ser liberto pelo provedor. O provedor pode definir todas, algumas ou nenhuma das propriedades do certificado. O provedor tem a opção de adiar até que o callback GET_CERT_PROPERTY seja chamado. É recomendável que os provedores definam o maior número possível de propriedades para permitir a cópia para outra loja.

Os seguintes tipos de localização de certificado são suportados no CertFindCertificateInStore:

• CERT_FIND_ANY
• CERT_FIND_SHA1_HASH
• CERT_FIND_MD5_HASH
• CERT_FIND_PROPERTY
• CERT_FIND_PUBLIC_KEY
• CERTIFICADO_ENCONTRAR_NOME_DO_SUJEITO
• CERT_FIND_SUBJECT_ATTR
• CERT_FIND_ISSUER_NAME
• CERT_FIND_ISSUER_ATTR
• CERT_FIND_SUBJECT_STR_A
• CERT_FIND_SUBJECT_STR_W
• CERT_FIND_ISSUER_STR_A
• CERT_FIND_ISSUER_STR_W
• CERT_FIND_KEY_SPEC
• CERT_FIND_ENHKEY_USAGE

O retorno de chamada FIND_CERT é chamado para cada um dos tipos de procura acima. Os parâmetros passados para CertFindCertificateInStore são copiados diretamente para a estrutura CERT_STORE_PROV_FIND_INFO antes de o callback FIND_CERT ser chamado. Para obter detalhes sobre os valores dos campos para os diferentes tipos de pesquisa da estrutura CERT_STORE_PROV_FIND_INFO, consulte CertFindCertificateInStore.

Os seguintes tipos de localização de certificado suportam as APIs CertGetSubjectCertificateFromStore e CertGetIssuerCertificateFromStore e ajudam a determinar se o certificado já existe na loja antes de adicionar:

• CERT_FIND_SUBJECT_CERT
• "Encontrar_emissor_do_certificado" (if adaptation is necessary while retaining the original reference: "CERT_FIND_ISSUER_OF (Encontrar Emissor do Certificado)")
• CERT_FIND_EXISTING

Para CERT_FIND_SUBJECT_CERT, o parâmetro pvFindPara aponta para uma estrutura CERT_INFO que contém o Emissor e o Número de Série do sujeito. Para CERT_FIND_ISSUER_OF, pvFindPara aponta para uma estrutura CERT_CONTEXT, do sujeito. Para CERT_FIND_EXISTING, pvFindPara aponta para um CERT_CONTEXT do certificado para verificar a sua existência no repositório.

O retorno de chamada FREE_FIND_CERT é chamado quando o certificado retornado pelo retorno de chamada FIND_CERT não foi liberado por ser usado em uma próxima FIND_CERT subsequente, tendo assim sua contagem de referência reduzida a zero, ou sendo liberada por uma chamada para CertCloseStore. Antes do retorno de chamada CLOSE ser chamado, todos os certificados retornados pelo retorno de chamada FIND_CERT devem ser liberados para o provedor sendo passados para uma chamada para o retorno de chamada FIND_CERT ou uma chamada para o retorno de chamada FREE_FIND_CERT. O mesmo se aplica aos retornos de chamada CRL e CTL.

O retorno de chamada GET_CERT_PROPERTY é chamado por CertGetCertificateContextProperty se não puder encontrar a propriedade especificada para o parâmetro pCertContext. O mesmo se aplica aos GET_CRL_PROPERTY e GET_CTL_PROPERTY.

O retorno de chamada FIND_CRL é chamado quando as APIs de armazenamento enumeram ou obtêm CRLs e antes de adicionar uma CRL. Os seguintes tipos de procura de CRL serão definidos:

Por CRL_FIND_ISSUED_BY, pvFindPara é um ponteiro para um CERT_CONTEXT do emissor da CRL. Por CRL_FIND_EXISTING, pvFindPara é um ponteiro para uma CRL_CONTEXT da CRL para determinar se ela já existe na loja.

O retorno de chamada FIND_CTL é invocado quando as APIs de armazenamento enumeram ou localizam CTLs. Os seguintes tipos de localização de CTL são suportados em CertFindCTLInStore:

• CTL_FIND_ANY
• CTL_FIND_SHA1_HASH
• CTL_FIND_MD5_HASH
• CTL_ENCONTRAR_USO
• CTL_FIND_SUBJECT
• CTL_FIND_EXISTING

A função de retorno FIND_CTL é chamada para cada um dos tipos de pesquisa acima. Os parâmetros passados para CertFindCTLInStore são copiados diretamente para a estrutura CERT_STORE_PROV_FIND_INFO antes que o retorno de chamada FIND_CTL seja chamado. Para obter detalhes sobre os valores de campo para os diferentes tipos de pesquisa da estrutura CERT_STORE_PROV_FIND_INFO, consulte CertFindCTLInStore.

O tipo de localização de CTL CTL_FIND_EXISTING ajuda a determinar se a CTL já existe na loja antes de fazer uma adição de CTL.

Por CTL_FIND_EXISTING, pvFindPara é um ponteiro para a estrutura CTL_CONTEXT da CTL para determinar se ela já existe na loja.