Função CertFindCertificateInStore (wincrypt.h)
A função de CertFindCertificateInStore
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
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
[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.
| 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.
Observação 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 de CERT_ID.
Localize o certificado identificado pelo CERT_IDespecificado. |
|
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 pszUsageIdentifier membro da estrutura CTL_USAGE. |
|
Tipo de dados depvFindPara Pesquisa um certificado no repositório que tenha um uso de chave Um certificado terá uma extensão de uso de chave aprimorada se tiver uma estrutura de 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, 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 NULL em 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 de 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 de CRYPT_HASH_BLOB. |
|
Tipo de dados de pvFindPara: NULL, não usado.
Pesquisa um certificado que tenha uma chave privada. A chave pode ser efêmera ou salva em disco. A chave pode ser uma chave CAPI (API de Criptografia) herdada ou uma chave CNG.
Observação 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 de CERT_RDN_ATTR que procuram uma correspondência com os atributos do emissor do certificado. Se o pszObjId Se o dwValueType membro do CERT_RDN_ATTR for CERT_RDN_ANY_TYPE, o tipo de valor será ignorado. Se o pbData membro do 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 dwCertEncodingType. |
|
Tipo de dados de pvFindPara: estrutura de CERT_NAME_BLOB.
Pesquise um certificado com uma correspondência exata de todo o nome do emissor com o nome no |
|
Tipo de dados de pvFindPara: estrutura de CERT_CONTEXT.
Pesquisa um certificado com um assunto 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 formatado como CERT_SIMPLE_NAME_STR. Em seguida, uma correspondência de subcadeia de caracteres que não diferencia maiúsculas de minúsculas dentro de uma cadeia de caracteres é executada. Quando esse valor é definido, a pesquisa é restrita a certificados cujo tipo de codificação corresponde dwCertEncodingType. Se a correspondência de subcadeia de caracteres falhar e o assunto contiver um RDN de email com cadeia de caracteres codificada por 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 de 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 de DWORD que contém um identificador de propriedade.
Pesquisa um certificado com uma propriedade que corresponde ao identificador de propriedade especificado pelo valor |
|
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 de 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 de CRYPT_HASH_BLOB. |
|
Tipo de dados de pvFindPara: estrutura de CRYPT_HASH_BLOB.
Pesquisa um certificado com um hash SHA1 + SHA256 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 SHA256 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 pszObjId Se o dwValueType membro do CERT_RDN_ATTR for CERT_RDN_ANY_TYPE, o tipo de valor será ignorado. Se o pbData membro do 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 dwCertEncodingType. |
|
Tipo de dados de pvFindPara: estrutura de 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 formatado como CERT_SIMPLE_NAME_STR. Em seguida, uma correspondência de subcadeia de caracteres que não diferencia maiúsculas de minúsculas dentro de uma cadeia de caracteres é executada. Quando esse valor é definido, a pesquisa é restrita a certificados cujo tipo de codificação corresponde 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 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
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.
Um
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 |
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
Os seguintes valores de dwFindFlags
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
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
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | wincrypt.h |
| biblioteca | Crypt32.lib |
| de DLL |
Crypt32.dll |
Consulte também
CertAddCertificateContextToStore
CertAddCertificateLinkToStore
CertDuplicateCertificateContext
CertNameToStr