Função CertFindChainInStore (wincrypt.h)

Artigo
03/15/2023

A função CertFindChainInStore localiza o primeiro ou o próximo certificado em um repositório que atende aos critérios especificados. Em seguida, ele compila 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, dwFindType e 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 para 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 para 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 que foi usado para codificar o repositório. O identificador de tipo de codificação de mensagem , contido no WORD 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 valores a seguir 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 a chave pública do provedor de serviços criptográficos. Essa comparação é a última marcar feita na cadeia quando ela é criada. Como o membro hCryptProv de um emissor contém uma chave privada, ele pode precisar ser verificado 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 sinalizador definido, o padrão é substituído e cadeias simples subsequentes também são verificadas quanto a 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 pesquisa 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	Abre apenas os repositórios de certificados do Computador Local. Os repositórios de certificados do usuário atual não são abertos.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Nenhuma marcar é 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 do emissor que corresponda a um de um conjunto de nomes de emissor.

Essa função comparará o nome BLOBs passados na estrutura pvFindPara a qualquer AC (autoridade de certificação ) 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 por meio de chamadas para a função CertVerifyRevocation e localizar a cadeia inadequada, uma chamada adicional para a função CertFindChainInStore não retornará uma cadeia que inclui o mesmo certificado da autoridade de certificação válida. Em vez disso, ele 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 para os quais esse parâmetro aponta dependem do valor do parâmetro dwFindType .

[in] pPrevChainContext

Um ponteiro para uma estrutura CERT_CHAIN_CONTEXT retornada de uma chamada anterior para essa função. A pesquisa é iniciada a partir deste certificado. Para a primeira chamada a essa função, esse parâmetro deve ser NULL. Em 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 retornado

Se o primeiro ou o 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 .

Comentários

O parâmetro pPrevChainContext deve ser NULL na primeira chamada para criar o contexto de 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 sempre será liberada por essa função usando a função CertFreeCertificateChain , mesmo que ocorra um erro.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll