Função CertFindCTLInStore (wincrypt.h)

Artigo
07/16/2024

A função CertFindCTLInStore localiza a primeira ou a próxima de dados de confiança de certificado (CTL) de contexto que corresponde aos critérios de pesquisa estabelecidos pelo dwFindType e seus pvFindPara associados. Essa função pode ser usada em um loop para localizar todos os contextos de 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 mensagens e certificados combinando-os com uma operação deOU bit 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

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

[in] dwFindFlags

Pode ser definido quando dwFindType está 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 ser 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 correspondente 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 correspondente 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, identificador de lista ou signatário na estrutura CTL_FIND_USAGE_PARA. Se o cUsageIdentifier membro for de tamanho de SubjectUsage, qualquer CTL será uma correspondência. Se o membro cbData membro do ListIdentifier membro for zero, qualquer identificador de lista será uma correspondência. Se o cbData membro do 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 de CTL será uma correspondência e somente os membros do Emissor e SerialNumber na estrutura deCERT_INFO do pSigner. Se pSigner for CTL_FIND_NO_SIGNER_PTR, apenas 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 correspondidos. 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 que tem o assunto especificado é encontrada. CertFindSubjectInCTL pode ser chamado para obter um ponteiro para a entrada do assunto na CTL. O membro pUsagePara no CTL_FIND_SUBJECT_PARA pode, opcionalmente, 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 na loja. Ctls sucessivas são recuperadas definindo pPrevCtlContext para 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 por CertDeleteCTLFromStore são ignorados. Essa função libera o CTL_CONTEXT referenciado por valores de NULL nãodesse parâmetro.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será um ponteiro para um contexto deCTL 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.

Observações

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 null nãopPrevCtlContext 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
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