Função CertFindChainInStore (wincrypt.h)

Artigo
07/16/2024

A função CertFindChainInStore localiza o primeiro ou o próximo certificado em um repositório que atenda aos critérios especificados. Em seguida, ele cria e verifica um contexto de cadeia de certificados para esse certificado. O certificado encontrado e para o qual a cadeia é criada é selecionado de acordo com os critérios estabelecidos pelos parâmetros dwFindFlags, dwFindTypee parâmetros de pvFindPara. 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 e criar um contexto de cadeia de certificados para cada certificado encontrado.

Sintaxe

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Parâmetros

[in] hCertStore

O identificador do repositório a ser pesquisado em busca de um certificado no qual uma cadeia é criada. Esse identificador é passado como um repositório adicional para a função CertGetCertificateChain à medida que a cadeia é criada.

[in] dwCertEncodingType

O tipo de codificação de certificado usado para codificar o repositório. O tipo de codificação de mensagem identificador, contido no WORD de alto desse valor, é ignorado por essa função.

Esse parâmetro pode ser o seguinte tipo de codificação de certificado definido no momento.

Valor	Significado
X509_ASN_ENCODING 1 (0x1)	Especifica a codificação de certificado X.509.

[in] dwFindFlags

Contém opções adicionais para a pesquisa. Os valores possíveis para esse parâmetro dependem do valor do parâmetro dwFindType.

Esse parâmetro pode conter zero ou uma combinação de um ou mais dos seguintes valores quando dwFindType contém CERT_CHAIN_FIND_BY_ISSUER.

Valor	Significado
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Compara a chave pública no certificado com o de chave pública do provedor de serviços criptográficos. Essa comparação é a última verificação feita na cadeia quando ela é criada. Como o hCryptProv membro de um emissor contém uma chave privada, talvez seja necessário verificar várias vezes durante esse processo; para facilitar essa verificação, o membro dwAcquirePrivateKeyFlags pode ser definido na estrutura CERT_CHAIN_FIND_BY_ISSUER_PARA para habilitar o cache desse hCryptProv.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Por padrão, somente a primeira cadeia simples é verificada quanto a correspondências de nome do emissor. Com esse conjunto de sinalizadores, o padrão é substituído e cadeias simples subsequentes também são verificadas para correspondências de nome do emissor.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Melhora o desempenho dessa função fazendo com que ela pesquise apenas os repositórios de sistema armazenados em cache (Root, My, Ca, Trust) para localizar certificados do emissor. Se esse sinalizador não estiver definido, a função pesquisará os repositórios de sistema armazenados em cache e o repositório representado pelo parâmetro hCertStore.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Somente o cache de URL é pesquisado. A Internet não é pesquisada.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Só abre os repositórios de certificados do Computador Local. Os repositórios de certificados do usuário atual não estão abertos.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Nenhuma verificação é feita para determinar se o certificado tem uma chave privada associada.

[in] dwFindType

Determina quais critérios usar para localizar um certificado no repositório.

Esse parâmetro pode ser o seguinte valor definido no momento.

CERT_CHAIN_FIND_BY_ISSUER

Localiza o certificado com base no nome do emissor. O parâmetro pvFindPara é um ponteiro para uma estrutura CERT_CHAIN_FIND_BY_ISSUER_PARA que contém membros que modificam a pesquisa.

A cadeia de certificados é criada para um certificado com uma chave privada disponível. Por padrão, somente os emissores na primeira cadeia simples são comparados em uma correspondência de nome do emissor. Se esse sinalizador estiver definido, todas as cadeias serão verificadas quanto a um certificado emissor que corresponda a um de um conjunto de nomes de emissor.

Essa função comparará o nome BLOBs passados na estrutura de pvFindPara com qualquer autoridade de certificação (AC) na cadeia, não apenas a autoridade de certificação no certificado raiz.

Essa função não executa nenhuma verificação de revogação.

Se pPrevChainContext não for NULL, essa função retornará uma cadeia para um certificado diferente sempre que a função for chamada. Se houver apenas um certificado adequado, mas houver duas autoridades de certificação emissoras correspondentes, uma das quais é revogada, é possível que essa função retorne a cadeia revogada. Se o aplicativo verificar a revogação em si por meio de chamadas para a função CertVerifyRevocation e achar a cadeia inadequada, uma chamada adicional à função CertFindChainInStore não retornará uma cadeia que inclua o mesmo certificado da autoridade de certificação válida. Em vez disso, retornará uma cadeia completamente diferente com um certificado diferente ou NULL, se nenhuma cadeia desse tipo puder ser encontrada.

[in] pvFindPara

Um ponteiro que contém critérios de pesquisa adicionais. O tipo e o formato dos dados que esse parâmetro aponta dependem do valor do parâmetro dwFindType.

[in] pPrevChainContext

Um ponteiro para uma estrutura de CERT_CHAIN_CONTEXT retornada de uma chamada anterior para essa função. A pesquisa é iniciada a partir desse certificado. Para a primeira chamada para essa função, esse parâmetro deve ser NULL. Nas chamadas subsequentes, é o ponteiro retornado pela chamada anterior para a função. Se esse parâmetro não for NULL, essa função liberará essa estrutura.

Valor de retorno

Se o primeiro ou próximo contexto de cadeia não for criado, NULL será retornado. Caso contrário, um ponteiro para uma estrutura de CERT_CHAIN_CONTEXT somente leitura será retornado. A estrutura CERT_CHAIN_CONTEXT é liberada quando passada como o parâmetro pPrevChainContext em uma chamada subsequente para essa função. Caso contrário, a estrutura CERT_CHAIN_CONTEXT deve ser liberada explicitamente chamando a função CertFreeCertificateChain.

Observações

O parâmetro pPrevChainContext deve ser NULL na primeira chamada para criar o contexto da cadeia. Para criar o próximo contexto de cadeia, o pPrevChainContext é definido como a estrutura CERT_CHAIN_CONTEXT retornada por uma chamada anterior. Se pPrevChainContext não for NULL, a estrutura será sempre liberada por essa função usando a função CertFreeCertificateChain, mesmo se ocorrer um erro.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Crypt32.lib
de DLL	Crypt32.dll