Função CertFindCertificateInStore (wincrypt.h)

A função de CertFindCertificateInStore localiza o primeiro ou próximo de contexto de de certificado em um repositório de certificados que corresponde a um critério de pesquisa estabelecido pelo dwFindType e seu pvFindPara associado. Essa função pode ser usada em um loop para localizar todos os certificados em um repositório de certificados que correspondam aos critérios de localização especificados.

Sintaxe

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parâmetros

[in] hCertStore

Um identificador do repositório de certificados a ser pesquisado.

[in] dwCertEncodingType

Especifica o tipo de codificação usado. Os tipos de codificação de mensagens e certificado devem ser especificados combinando-os com uma operação or debit a bit, conforme mostrado no exemplo a seguir:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING tipos de codificação definidos atualmente são:

• X509_ASN_ENCODING
• PKCS_7_ASN_ENCODING

[in] dwFindFlags

Usado com alguns valores de dwFindType para modificar os critérios de pesquisa. Para a maioria dos valores dwFindType , dwFindFlags não é usado e deve ser definido como zero. Para obter informações detalhadas, consulte Comentários.

[in] dwFindType

Especifica o tipo de pesquisa que está sendo feita. O tipo de pesquisa determina o tipo de dados, o conteúdo e o uso de pvFindPara. Esse parâmetro pode ser um dos valores a seguir.

[in] pvFindPara

Aponta para um item de dados ou estrutura usado com dwFindType.

[in] pPrevCertContext

Um ponteiro para a última estrutura de CERT_CONTEXT retornada por essa função. Esse parâmetro deve ser NULL na primeira chamada da função. Para localizar certificados sucessivos que atendem aos critérios de pesquisa, defina pPrevCertContext para o ponteiro retornado pela chamada anterior para a função. Essa função libera o CERT_CONTEXT referenciado por valores de NULL nãodesse parâmetro.

Valor de retorno

Se a função for bem-sucedida, a função retornará um ponteiro para uma estrutura de CERT_CONTEXT somente leitura.

Se a função falhar e um certificado que corresponde aos critérios de pesquisa não for encontrado, o valor retornado será NULL.

UmCERT_CONTEXT NULL nãoque retorno de CertFindCertificateInStore deve ser liberado pelo CertFreeCertificateContext ou sendo passado como o parâmetro pPrevCertContext em uma chamada subsequente para CertFindCertificateInStore.

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

Observações

O parâmetro dwFindFlags é usado para modificar os critérios de alguns tipos de pesquisa.

O valor dwFindFlags CERT_UNICODE_IS_RDN_ATTRS_FLAG é usado apenas com os valores CERT_FIND_SUBJECT_ATTR e CERT_FIND_ISSUER_ATTR para dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG deve ser definido se a estrutura de CERT_RDN_ATTR apontada por pvFindPara foi inicializada com cadeias de caracteres Unicode. Antes que qualquer comparação seja feita, a cadeia de caracteres a ser correspondida é convertida usando X509_UNICODE_NAME para fornecer comparações Unicode.

Os seguintes valores de dwFindFlags são usados apenas com o valor CERT_FIND_ENKEY_USAGE para dwFindType:

CertDuplicateCertificateContext pode ser chamado para fazer uma duplicata do contexto retornado. O contexto retornado pode ser adicionado a um repositório de certificados diferente usando CertAddCertificateContextToStore ou um link para esse contexto de certificado pode ser adicionado a um repositório que não é um repositório de coleções usando CertAddCertificateLinkToStore.

O ponteiro retornado é liberado quando passado como o parâmetro pPrevCertContext em uma chamada subsequente para a função. Caso contrário, o ponteiro deve ser liberado explicitamente chamando CertFreeCertificateContext. Um pPrevCertContext que não é NULL é sempre liberado pelo CertFindCertificateInStore usando uma chamada para CertFreeCertificateContext, mesmo que haja um erro na função.

Exemplos

O exemplo a seguir mostra como encontrar um contexto de certificado no repositório de certificados atendendo a um critério de pesquisa. Para obter um exemplo completo que inclui o contexto deste exemplo, consulte Exemplo de Programa C: Operações do Repositório de Certificados.

Para obter outro exemplo que usa essa função, consulte Exemplo de Programa C: Operações do Repositório de Certificados de Coleção e Irmão.

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

#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE  hSystemStore;              // The system store handle.
PCCERT_CONTEXT  pDesiredCert = NULL;   // Set to NULL for the first 
                                       // call to
                                       // CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";


//-------------------------------------------------------------------
// Open the certificate store to be searched.

if(hSystemStore = CertOpenStore(
     CERT_STORE_PROV_SYSTEM, 
     0,                      // Encoding type not needed 
                             // with this PROV.
     NULL,                   // Accept the default HCRYPTPROV. 
     CERT_SYSTEM_STORE_CURRENT_USER,
                             // Set the system store location in 
                             // the registry.
     L"MY"))                 // Could have used other predefined 
                             // system stores
                             // including Trust, CA, or Root.
{
   printf("Opened the MY system store. \n");
}
else
{
   printf( "Could not open the MY system store.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its 
// subject. 

if(pDesiredCert=CertFindCertificateInStore(
      hSystemStore,
      MY_ENCODING_TYPE,           // Use X509_ASN_ENCODING.
      0,                          // No dwFlags needed. 
      CERT_FIND_SUBJECT_STR,      // Find a certificate with a
                                  // subject that matches the string
                                  // in the next parameter.
      lpszCertSubject ,           // The Unicode string to be found
                                  // in a certificate's subject.
      NULL))                      // NULL for the first call to the
                                  // function. In all subsequent
                                  // calls, it is the last pointer
                                  // returned by the function.
{
  printf("The desired certificate was found. \n");
}
else
{
   printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up. 

if(pDesiredCert)
    CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
    CertCloseStore(
        hSystemStore, 
        CERT_CLOSE_STORE_CHECK_FLAG);

Requisitos

Consulte também

CERT_CONTEXT

CertAddCertificateContextToStore

CertAddCertificateLinkToStore

CertDuplicateCertificateContext

CertEnumCertificatesInStore

CertFreeCertificateContext

CertGetCertificateChain

CertNameToStr

Funções de certificado