Estendendo a funcionalidade CertOpenStore

O repositório de certificados é central para todas as operações de gerenciamento de certificados. A funcionalidade da função CertOpenStore pode ser estendida por meio do uso de uma função instalável (ou registrada) certificate-store-provider. 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 USMT (Ferramenta de Migração de Estado do Usuário) do Windows.

 

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

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

O repositório TrustedPeople por usuário é restrito a repositórios físicos predefinidos. Não é possível estender o repositório TrustedPeople por usuário. No entanto, você pode estender o repositório TrustedPeople do computador local.

Windows XP e Windows Server 2003: O repositório TrustedPeople por usuário não está restrito a repositórios físicos predefinidos.

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

Conforme mostrado na ilustração a seguir, após a abertura do repositório, 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 os 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 repositório de certificados.

As APIs do repositório permitem que um provedor de repositório mantenha os certificados, CRLs e CTLs ( listas de confiança de certificado ) fora do cache do repositório (por exemplo, um banco de dados externo de certificados, como fornecido pelo Banco de Dados do Servidor de Certificados da Microsoft).

O CertOpenStore despacha por meio do parâmetro pszStoreProvider para a função de provedor instalável CertDllOpenStoreProv apropriada. O provedor retorna informações no parâmetro pStoreProvInfo que aponta para uma estrutura CERT_STORE_PROV_INFO . A estrutura CERT_STORE_PROV_INFO contém um membro dwStoreProvFlags . O sinalizador CERT_STORE_PROV_EXTERNAL_FLAG foi adicionado para permitir que o provedor indique que os certificados, as CRLs e as CTLs são externos ao cache do repositório.

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 dar 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
• 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 das funções de retorno de chamada CRL e CTL são idênticas à acima, com o ponteiro para o CERT_CONTEXT substituído por um ponteiro para um CRL_CONTEXT ou CTL_CONTEXT.

O retorno de chamada FIND_CERT é chamado quando as APIs do repositório enumeram, localizam ou adicionam certificados. pPrevCertContext e ppvStoreProvFindInfo são definidos como NULL para iniciar um novo FIND. O ppvStoreProvFindInfo retornado é passado novamente na próxima localização em que ele pode ser liberado 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 retorno de chamada GET_CERT_PROPERTY seja chamado. É recomendável que os provedores definam o máximo possível de propriedades para permitir a cópia para outro repositório.

Os seguintes tipos de localização de certificado têm suporte no CertFindCertificateInStore:

• CERT_FIND_ANY
• CERT_FIND_SHA1_HASH
• CERT_FIND_MD5_HASH
• CERT_FIND_PROPERTY
• CERT_FIND_PUBLIC_KEY
• CERT_FIND_SUBJECT_NAME
• 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 localização acima. Os parâmetros passados para CertFindCertificateInStore são copiados diretamente para a estrutura de CERT_STORE_PROV_FIND_INFO antes que o retorno de chamada FIND_CERT seja chamado. Para obter detalhes sobre os valores de campo para os diferentes tipos de localização da estrutura CERT_STORE_PROV_FIND_INFO, consulte CertFindCertificateInStore.

Os seguintes tipos de localização de certificado dão suporte às APIs CertGetSubjectCertificateFromStore e CertGetIssuerCertificateFromStore e ajudam a determinar se o certificado já existe no repositório antes de adicionar:

• CERT_FIND_SUBJECT_CERT
• CERT_FIND_ISSUER_OF
• CERT_FIND_EXISTING

Para CERT_FIND_SUBJECT_CERT, o parâmetro pvFindPara aponta para uma estrutura CERT_INFO que contém o Emissor e SerialNumber do assunto. Para CERT_FIND_ISSUER_OF, pvFindPara aponta para uma estrutura CERT_CONTEXT do assunto. Para CERT_FIND_EXISTING, pvFindPara aponta para uma CERT_CONTEXT do certificado a ser marcar por 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 um próximo FIND_CERT subsequente, tendo assim sua contagem de referênciacrementada para zero ou sendo liberado por uma chamada para CertCloseStore. Antes que o retorno de chamada CLOSE seja chamado, todos os certificados retornados pelo FIND_CERT retorno de chamada 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 será chamado por CertGetCertificateContextProperty se não puder encontrar a propriedade especificada para o parâmetro pCertContext . O mesmo vale para GET_CRL_PROPERTY e GET_CTL_PROPERTY.

O retorno de chamada FIND_CRL é chamado quando as APIs do repositório enumeram ou obtêm CRLs e antes de adicionar uma CRL. Os seguintes tipos de localização de CRL serão definidos:

Para CRL_FIND_ISSUED_BY, pvFindPara é um ponteiro para um CERT_CONTEXT do emissor de CRL. Para CRL_FIND_EXISTING, pvFindPara é um ponteiro para um CRL_CONTEXT da CRL para determinar se ela já existe no repositório.

O retorno de chamada FIND_CTL é chamado quando as APIs do repositório enumeram ou encontram CTLs. Os seguintes tipos de localização de CTL têm suporte no CertFindCTLInStore:

• CTL_FIND_ANY
• CTL_FIND_SHA1_HASH
• CTL_FIND_MD5_HASH
• CTL_FIND_USAGE
• CTL_FIND_SUBJECT
• CTL_FIND_EXISTING

O retorno de chamada FIND_CTL é chamado para cada um dos tipos de localização 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 localização da estrutura CERT_STORE_PROV_FIND_INFO, consulte CertFindCTLInStore.

O CTL_FIND_EXISTING tipo de localização CTL ajuda a determinar se a CTL já existe no repositório antes de fazer uma adição de CTL.

Para CTL_FIND_EXISTING, pvFindPara é um ponteiro para a estrutura CTL_CONTEXT da CTL para determinar se ela já existe no repositório.