Função CertEnumCertificatesInStore (wincrypt.h)

Artigo
08/27/2023

A função CertEnumCertificatesInStore recupera o primeiro ou o próximo certificado em um repositório de certificados. Usada em um loop, essa função pode recuperar em sequência todos os certificados em um repositório de certificados.

Sintaxe

PCCERT_CONTEXT CertEnumCertificatesInStore(
  [in] HCERTSTORE     hCertStore,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parâmetros

[in] hCertStore

Um identificador de um repositório de certificados.

[in] pPrevCertContext

Um ponteiro para o CERT_CONTEXT do contexto de certificado anterior encontrado.

Esse parâmetro deve ser NULL para iniciar a enumeração e obter o primeiro certificado no repositório. Certificados sucessivos são enumerados definindo pPrevCertContext como o ponteiro retornado por uma chamada anterior para a função. Essa função libera o CERT_CONTEXT referenciado por valores não NULL desse parâmetro.

Para repositórios lógicos, incluindo repositórios de coleção, uma duplicata do pCertContext retornado por essa função não pode ser usada para iniciar uma nova subsequência de enumerações porque o certificado duplicado perde o estado de enumeração inicial. A enumeração ignora qualquer certificado excluído anteriormente por CertDeleteCertificateFromStore.

Retornar valor

Se a função for bem-sucedida, a função retornará um ponteiro para o próximo CERT_CONTEXT no repositório. Se não houver mais certificados no repositório, a função retornará NULL.

Para obter informações de erro estendidas, chame GetLastError. Alguns códigos de erro possíveis seguem.

Valor	Descrição
E_INVALIDARG	O identificador no parâmetro hCertStore não é o mesmo que no contexto de certificado apontado por pPrevCertContext.
CRYPT_E_NOT_FOUND	Nenhum certificado foi encontrado. Isso acontece se o repositório está vazio ou se a função chegou ao final da lista do repositório.
ERROR_NO_MORE_FILES	Aplica-se a repositórios externos. Nenhum certificado foi encontrado. Isso acontece se o repositório está vazio ou se a função chegou ao final da lista do repositório.

Comentários

O ponteiro retornado é liberado quando passado como o parâmetro pPrevCertContext em uma chamada subsequente. Caso contrário, o ponteiro deverá ser liberado chamando CertFreeCertificateContext. Um pPrevCertContext não NULL passado para CertEnumCertificatesInStore é sempre liberado mesmo para um erro.

Uma duplicata do certificado atualmente enumerado pode ser feita chamando CertDuplicateCertificateContext.

Exemplos

O exemplo a seguir lista os contextos de certificado no repositório de certificados. Para obter outro exemplo que usa essa função, consulte Exemplo de programa C: excluindo certificados de um repositório de certificados.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")


//--------------------------------------------------------------------
// Declare and initialize variables.
HANDLE          hStoreHandle = NULL;
PCCERT_CONTEXT  pCertContext = NULL;   
char * pszStoreName = "CA";

//--------------------------------------------------------------------
// Open a system certificate store.
if (hStoreHandle = CertOpenSystemStore(
     NULL,     
     pszStoreName))
    {
         printf("The %s store has been opened. \n", pszStoreName);
    }
    else
    {
         printf("The store was not opened.\n");
         exit(1);
    }

//-------------------------------------------------------------------
// Find the certificates in the system store. 
while(pCertContext= CertEnumCertificatesInStore(
      hStoreHandle,
      pCertContext)) // on the first call to the function,
                     // this parameter is NULL 
                     // on all subsequent calls, 
                     // this parameter is the last pointer 
                     // returned by the function
{
    //----------------------------------------------------------------
    // Do whatever is needed for a current certificate.
    // ...
} // End of while.

//--------------------------------------------------------------------
//   Clean up.
if (!CertCloseStore(
         hStoreHandle,
         0))
{
    printf("Failed CertCloseStore\n");
    exit(1);
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll