Função CertFindCertificateInStore (wincrypt.h)
A função CertFindCertificateInStore localiza o primeiro ou o próximo contexto 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 certificado e de mensagem devem ser especificados combinando-os com uma operação or bit a bit, conforme mostrado no exemplo a seguir:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING Tipos de codificação definidos no momento são:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] dwFindFlags
Usado com alguns valores 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 usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Tipo de dados de pvFindPara: NULL, não usado.
Nenhum critério de pesquisa usado. Retorna o próximo certificado no repositório. Nota A ordem do contexto do certificado pode não ser preservada dentro do repositório.
Para acessar um certificado específico, você deve iterar entre os certificados no repositório.
|
|
Tipo de dados de pvFindPara: estrutura CERT_ID .
Localize o certificado identificado pelo CERT_ID especificado. |
|
Tipo de dados de pvFindPara: estrutura de CTL_USAGE .
Pesquisa um certificado que tenha uma extensão szOID_ENHANCED_KEY_USAGE ou um CERT_CTL_PROP_ID que corresponda ao membro pszUsageIdentifier da estrutura CTL_USAGE . |
|
Tipo de dados de pvFindPara: estrutura CERT_ENHKEY_USAGE .
Pesquisa um certificado no repositório que tem uma extensão de uso de chave aprimorada ou uma propriedade de uso de chave aprimorada e um identificador de uso que corresponde ao membro cUsageIdentifier na estrutura CERT_ENHKEY_USAGE . Um certificado terá uma extensão de uso de chave aprimorada se tiver uma estrutura de CERT_EXTENSION com o membro pszObjId definido como szOID_ENHANCED_KEY_USAGE. Um certificado terá uma propriedade de uso de chave aprimorada se seu identificador de CERT_ENHKEY_USAGE_PROP_ID estiver definido. Se CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG for definido em dwFindFlags, os certificados sem a extensão de uso de chave ou propriedade também serão correspondentes. Definir esse sinalizador tem precedência sobre a passagem de NULL no pvFindPara. Se CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG estiver definido, uma correspondência será feita somente na extensão de uso da chave. Para obter informações sobre modificações de sinalizador para critérios de pesquisa, consulte Comentários. |
|
Tipo de dados de pvFindPara: estrutura CERT_CONTEXT .
Pesquisa um certificado que é uma correspondência exata do contexto de certificado especificado. |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Pesquisa um certificado com um hash SHA1 que corresponde ao hash na estrutura CRYPT_HASH_BLOB . |
|
Tipo de dados de pvFindPara: NULL, não usado.
Pesquisa um certificado que tem uma chave privada. A chave pode ser efêmera ou salva no disco. A chave pode ser uma chave CAPI (API de Criptografia) herdada ou uma chave CNG. Nota A ordem do contexto do certificado pode não ser preservada dentro do repositório. Portanto, para acessar um certificado específico, você deve iterar em todos os certificados.
|
|
Tipo de dados de pvFindPara: estrutura de CERT_RDN .
Pesquisa um certificado com atributos de emissor especificados que correspondem a atributos na estrutura CERT_RDN . Se esses valores forem definidos, a função comparará atributos do emissor em um certificado com elementos da matriz CERT_RDN_ATTR nesta estrutura CERT_RDN . As comparações iteram por meio dos atributos CERT_RDN_ATTR procurando uma correspondência com os atributos do emissor do certificado. Se o membro pszObjId de CERT_RDN_ATTR for NULL, o identificador de objeto de atributo será ignorado. Se o membro dwValueType de CERT_RDN_ATTR for CERT_RDN_ANY_TYPE, o tipo de valor será ignorado. Se o membro pbData de CERT_RDN_VALUE_BLOB for NULL, qualquer valor será uma correspondência. Atualmente, há suporte apenas para uma correspondência exata que diferencia maiúsculas de minúsculas. Para obter informações sobre opções Unicode, consulte Comentários. Quando esses valores são definidos, a pesquisa é restrita a certificados cujo tipo de codificação corresponde a dwCertEncodingType. |
|
Tipo de dados de pvFindPara: estrutura de CERT_NAME_BLOB .
Pesquise um certificado com uma correspondência exata do nome inteiro do emissor com o nome no CERT_NAME_BLOB A pesquisa é restrita a certificados que correspondem ao dwCertEncodingType. |
|
Tipo de dados de pvFindPara: estrutura CERT_CONTEXT .
Pesquisa um certificado com uma entidade que corresponde ao emissor em CERT_CONTEXT. Em vez de usar CertFindCertificateInStore com esse valor, use a função CertGetCertificateChain . |
|
Tipo de dados de pvFindPara: cadeia de caracteres Unicode terminada em nulo.
Pesquisa um certificado que contém a cadeia de caracteres de nome do emissor especificada. O membro emissor do certificado é convertido em uma cadeia de caracteres de nome do tipo apropriado usando a forma apropriada de CertNameToStr formatada como CERT_SIMPLE_NAME_STR. Em seguida, uma correspondência de subcadeia de caracteres sem diferenciação de maiúsculas e minúsculas é executada. Quando esse valor é definido, a pesquisa é restrita a certificados cujo tipo de codificação corresponde a dwCertEncodingType. Se a correspondência de subcadeia de caracteres falhar e o assunto contiver um RDN de email com cadeia de caracteres codificada em Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG será usado para converter o assunto em uma cadeia de caracteres Unicode e a correspondência de subcadeia de caracteres será executada novamente. |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Pesquisa um certificado com uma propriedade CERT_KEY_IDENTIFIER_PROP_ID que corresponde ao identificador de chave em CRYPT_HASH_BLOB. |
|
Tipo de dados de pvFindPara: variável DWORD que contém uma especificação de chave.
Pesquisa um certificado que tem uma propriedade CERT_KEY_SPEC_PROP_ID que corresponde à especificação de chave em pvFindPara. |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Pesquisa um certificado com um hash MD5 que corresponde ao hash em CRYPT_HASH_BLOB. |
|
Tipo de dados de pvFindPara: variável DWORD que contém um identificador de propriedade.
Pesquisa um certificado com uma propriedade que corresponde ao identificador de propriedade especificado pelo valor DWORD em pvFindPara. |
|
Tipo de dados de pvFindPara: estrutura de CERT_PUBLIC_KEY_INFO .
Pesquisa um certificado com uma chave pública que corresponde à chave pública na estrutura CERT_PUBLIC_KEY_INFO . |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Pesquisa um certificado com um hash SHA1 que corresponde ao hash na estrutura CRYPT_HASH_BLOB . |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Pesquisa um certificado com um hash de assinatura que corresponde ao hash de assinatura na estrutura CRYPT_HASH_BLOB . |
|
Tipo de dados de pvFindPara: estrutura de CERT_RDN .
Pesquisa um certificado com atributos de entidade especificados que correspondem a atributos na estrutura CERT_RDN . Se os valores RDN forem definidos, a função comparará os atributos da entidade em um certificado com elementos da matriz CERT_RDN_ATTR nesta estrutura CERT_RDN . As comparações iteram por meio dos atributos CERT_RDN_ATTR procurando uma correspondência com os atributos da entidade do certificado. Se o membro pszObjId de CERT_RDN_ATTR for NULL, o identificador de objeto de atributo será ignorado. Se o membro dwValueType de CERT_RDN_ATTR for CERT_RDN_ANY_TYPE, o tipo de valor será ignorado. Se o membro pbData de CERT_RDN_VALUE_BLOB for NULL, qualquer valor será uma correspondência. Atualmente, há suporte apenas para uma correspondência exata que diferencia maiúsculas de minúsculas. Para obter informações sobre opções Unicode, consulte Comentários. Quando esses valores são definidos, a pesquisa é restrita a certificados cujo tipo de codificação corresponde a dwCertEncodingType. |
|
Tipo de dados de pvFindPara: estrutura CERT_INFO .
Pesquisa um certificado com um emissor e um número de série que correspondem ao emissor e ao número de série na estrutura CERT_INFO . |
|
Tipo de dados de pvFindPara: estrutura de CERT_NAME_BLOB .
Pesquisa um certificado com uma correspondência exata de todo o nome da entidade com o nome na estrutura CERT_NAME_BLOB . A pesquisa é restrita a certificados que correspondem ao valor de dwCertEncodingType. |
|
Tipo de dados de pvFindPara: cadeia de caracteres Unicode terminada em nulo.
Pesquisa um certificado que contém a cadeia de caracteres de nome da entidade especificada. O membro da entidade do certificado é convertido em uma cadeia de caracteres de nome do tipo apropriado usando a forma apropriada de CertNameToStr formatada como CERT_SIMPLE_NAME_STR. Em seguida, uma correspondência de subcadeia de caracteres sem diferenciação de maiúsculas e minúsculas é executada. Quando esse valor é definido, a pesquisa é restrita a certificados cujo tipo de codificação corresponde a dwCertEncodingType. |
|
Tipo de dados de pvFindPara: não usado.
Localize um certificado que tenha uma extensão ou uma propriedade de ponto de distribuição de certificado cruzado. |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB .
Localize um certificado cuja chave pública com hash MD5 corresponda ao hash especificado. |
[in] pvFindPara
Aponta para um item de dados ou estrutura usado com dwFindType.
[in] pPrevCertContext
Um ponteiro para a última estrutura 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 como o ponteiro retornado pela chamada anterior para a função. Essa função libera o CERT_CONTEXT referenciado por valores não NULL desse parâmetro.
Retornar valor
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.
Um CERT_CONTEXT não NULL que CertFindCertificateInStore retorna deve ser liberado por CertFreeCertificateContext ou ser 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.
| Código de retorno | Descrição |
|---|---|
|
Nenhum certificado foi encontrado que corresponda aos critérios de pesquisa. Isso pode acontecer se o repositório estiver vazio ou o final da lista do repositório for atingido. |
|
O identificador no parâmetro hCertStore não é o mesmo que no contexto de certificado apontado pelo parâmetro pPrevCertContext ou um valor que não é válido foi especificado no parâmetro dwFindType . |
Comentários
O parâmetro dwFindFlags é usado para modificar os critérios de alguns tipos de pesquisa.
O valor CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags é 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 dwFindFlags são usados apenas com o valor CERT_FIND_ENKEY_USAGE para dwFindType:
CertDuplicateCertificateContext pode ser chamado para tornar 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 por CertFindCertificateInStore usando uma chamada para CertFreeCertificateContext, mesmo que haja um erro na função.
Exemplos
O exemplo a seguir mostra a localização de 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 para este 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 de repositório de certificados irmãos e coleções.
#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
| 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 |
Confira também
CertAddCertificateContextToStore
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de