Função CertFindCTLInStore (wincrypt.h)

Artigo
08/27/2023

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

Sintaxe

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parâmetros

[in] hCertStore

Identificador do repositório de certificados a ser pesquisado.

[in] dwMsgAndCertEncodingType

Especifica o tipo de codificação usado na CTL. É sempre aceitável especificar os tipos de codificação de certificado e mensagem 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

Esse parâmetro é usado somente quando o parâmetro dwFindType é definido como CTL_FIND_USAGE.

[in] dwFindFlags

Pode ser definido quando dwFindType é definido como CTL_FIND_USAGE. Para obter detalhes, consulte os comentários em CTL_FIND_USAGE, a seguir.

[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
CTL_FIND_ANY	Tipo de dados de pvFindPara: NULL. Qualquer CTL é uma correspondência.
CTL_FIND_SHA1_HASH	Tipo de dados de pvFindPara: CRYPT_HASH_BLOB. Uma CTL com um hash que corresponde ao hash na estrutura CRYPT_HASH_BLOB é encontrada.
CTL_FIND_MD5_HASH	Tipo de dados de pvFindPara: CRYPT_HASH_BLOB. Uma CTL com um hash que corresponde ao hash na estrutura CRYPT_HASH_BLOB é encontrada.
CTL_FIND_USAGE	Tipo de dados de pvFindPara: CTL_FIND_USAGE_PARA. Qualquer CTL encontrada que tenha um identificador de uso, identificador de lista ou signatário que corresponda ao identificador de uso, ao identificador de lista ou ao signatário na estrutura CTL_FIND_USAGE_PARA . Se o membro cUsageIdentifier for do tamanho subjectUsage , qualquer CTL será uma correspondência. Se o membro cbData do membro ListIdentifier for zero, qualquer identificador de lista será uma correspondência. Se o membro cbData de ListIdentifier for CTL_FIND_NO_LIST_ID_CBDATA, apenas uma CTL sem um identificador de lista será uma correspondência. Se o membro pSigner na estrutura CTL_FIND_USAGE_PARA for NULL, qualquer signatário ctl será uma correspondência e somente os membros Issuer e SerialNumber na estrutura de CERT_INFOdo pSigner serão usados. Se pSigner for CTL_FIND_NO_SIGNER_PTR, somente uma CTL sem um signatário será uma correspondência.
CTL_FIND_SAME_USAGE_FLAG	Tipo de dados de pvFindPara: CTL_FIND_USAGE_PARA. Somente CTLs com exatamente os mesmos identificadores de uso são correspondidas. Ctls com identificadores de uso adicionais não são correspondentes. Por exemplo, se apenas "1.2.3" for especificado na estrutura CTL_FIND_USAGE_PARA , para uma correspondência, a CTL deverá conter apenas "1.2.3" e nenhum identificador de uso adicional.
CTL_FIND_EXISTING	Tipo de dados de pvFindPara: PCCTL_CONTEXT. Pesquisa a próxima CRL que é uma correspondência exata do CTL_CONTEXT.
CTL_FIND_SUBJECT	Tipo de dados de pvFindPara: CTL_FIND_SUBJECT_PARA. Uma CTL com o assunto especificado foi encontrada. CertFindSubjectInCTL pode ser chamado para obter um ponteiro para a entrada do assunto na CTL. Opcionalmente, o membro pUsagePara no CTL_FIND_SUBJECT_PARA pode ser definido para habilitar a correspondência descrita anteriormente em CTL_FIND_USAGE.

[in] pvFindPara

Um ponteiro para o valor de pesquisa associado ao parâmetro dwFindType .

[in] pPrevCtlContext

Um ponteiro para o último CTL_CONTEXT retornado por essa função. Deve ser NULL para obter a primeira CTL no repositório. Ctls sucessivas são recuperadas definindo pPrevCtlContext como o ponteiro para o CTL_CONTEXT retornado por uma chamada de função anterior. Todos os certificados que não atendem aos critérios de pesquisa ou que foram excluídos anteriormente pelo CertDeleteCTLFromStore são ignorados. Essa função libera o CTL_CONTEXT referenciado por valores não NULL desse parâmetro.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um ponteiro para um contexto CTL somente leitura.

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

Código de retorno	Descrição
CRYPT_E_NOT_FOUND	Nenhuma CTL foi encontrada no repositório, nenhuma CTL foi encontrada correspondendo aos critérios de pesquisa ou a função chegou ao final da lista do repositório.
E_INVALIDARG	O identificador no parâmetro hCertStore não é o mesmo que no contexto CTL apontado pelo parâmetro pPrevCtlContext ou um valor que não é válido foi especificado no parâmetro dwFindType .

Comentários

Um ponteiro retornado é liberado quando passado como o pPrevCtlContext em uma chamada subsequente para a função. Caso contrário, o ponteiro deve ser liberado chamando CertFreeCTLContext. Um pPrevCtlContext não NULL passado para a função sempre é liberado com uma chamada para CertFreeCTLContext, mesmo que a função gere um erro.

CertDuplicateCTLContext pode ser chamado para fazer uma duplicata do contexto retornado. O contexto ctl retornado pode ser adicionado a um repositório de certificados diferente usando CertAddCTLContextToStore ou um link para esse contexto CTL pode ser adicionado a um repositório de não coleção usando CertAddCTLLinkToStore. Se uma CTL que corresponde aos critérios de pesquisa não for encontrada, NULL será retornado.

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