Função CertGetCertificateChain (wincrypt.h)

Artigo
07/16/2024

A função CertGetCertificateChain cria um contexto de cadeia de certificados começando de um certificado final e voltando, se possível, para um certificado raiz confiável.

Sintaxe

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

Parâmetros

[in, optional] hChainEngine

Um identificador do mecanismo de cadeia (namespace e cache) a ser usado. Se hChainEngine for NULL, o mecanismo de cadeia padrão, HCCE_CURRENT_USER, será usado. Esse parâmetro pode ser definido como HCCE_LOCAL_MACHINE.

[in] pCertContext

Um ponteiro para o CERT_CONTEXT do certificado final, o certificado para o qual uma cadeia está sendo criada. Esse contexto de certificado será o elemento de índice zero na primeira cadeia simples.

[in, optional] pTime

Um ponteiro para uma variável FILETIME que indica o tempo para o qual a cadeia deve ser validada. Observe que o tempo não afeta a lista de confiança, a revogação ou a verificação do repositório raiz. A hora atual do sistema será usada se NULL for passado para esse parâmetro. A confiança em um determinado certificado sendo uma raiz confiável baseia-se no estado atual do repositório raiz e não no estado do repositório raiz em um momento passado por esse parâmetro. Para revogação, uma lista de revogação de certificados (CRL), em si, deve ser válida no momento atual. O valor desse parâmetro é usado para determinar se um certificado listado em uma CRL foi revogado.

[in] hAdditionalStore

Um identificador para qualquer repositório adicional para pesquisar certificados de suporte e listas de confiança de certificado (CTLs). Esse parâmetro poderá ser NULL se nenhum repositório adicional for pesquisado.

[in] pChainPara

Um ponteiro para uma estrutura de CERT_CHAIN_PARA que inclui parâmetros de criação de cadeia.

[in] dwFlags

Valores de sinalizador que indicam processamento especial. Esse parâmetro pode ser uma combinação de um ou mais dos sinalizadores a seguir.

Valor	Significado
CERT_CHAIN_CACHE_END_CERT 0x00000001	Quando esse sinalizador é definido, o certificado final é armazenado em cache, o que pode acelerar o processo de criação de cadeias. Por padrão, o certificado final não é armazenado em cache e precisa ser verificado sempre que uma cadeia for criada para ele.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY 0x80000000	A verificação de revogação acessa apenas URLs armazenadas em cache.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT 0x04000000	Esse sinalizador é usado internamente durante a criação da cadeia para um certificado de protocolo de status de certificado online (OCSP) para impedir verificações de revogação cíclica. Durante a criação da cadeia, se a resposta OCSP for assinada por um signatário OCSP independente, além do build da cadeia original, haverá uma segunda cadeia criada para o próprio certificado do signatário OCSP. Esse sinalizador é usado durante este segundo build de cadeia para inibir um certificado de signatário OCSP independente recursivo. Se o certificado do signatário contiver a extensão szOID_PKIX_OCSP_NOCHECK, a verificação de revogação será ignorada para o certificado do signatário folha. A verificação de OCSP e CRL é permitida. Windows Server 2003 e Windows XP: Esse valor não tem suporte.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL 0x00000004	Usa apenas URLs armazenadas em cache na criação de uma cadeia de certificados. A Internet e a intranet não são pesquisadas por objetos baseados em URL. Observação Este sinalizador não é aplicável à verificação de revogação. Defina CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY para usar apenas URLs armazenadas em cache para verificação de revogação.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING 0x00000040	Por motivos de desempenho, a segunda passagem da construção da cadeia considera apenas possíveis caminhos de cadeia com qualidade maior ou igual à mais alta qualidade determinada durante a primeira passagem. A primeira passagem considera apenas assinatura válida, cadeia completa e raízes confiáveis para calcular a qualidade da cadeia. Esse sinalizador pode ser definido para desabilitar essa otimização e considerar todos os possíveis caminhos de cadeia durante a segunda passagem.
CERT_CHAIN_DISABLE_MY_PEER_TRUST 0x00000800	Não há suporte para esse sinalizador. Os certificados no repositório "Meu" nunca são considerados para confiança de pares.
CERT_CHAIN_ENABLE_PEER_TRUST 0x00000400	Os certificados de entidade final no repositório "TrustedPeople" são confiáveis sem executar nenhum edifício de cadeia. Essa função não define os bits de membro CERT_TRUST_IS_PARTIAL_CHAIN ou CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus do parâmetro ppChainContext . Windows Server 2003 Windows XP: Não há suporte para esse sinalizador.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE 0x00010000	Definir esse sinalizador indica que o chamador deseja optar por verificações de assinatura fracas. Esse sinalizador está disponível na atualização cumulativo para cada sistema operacional começando com o Windows 7 e o Windows Server 2008 R2.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS 0x00000080	O padrão é retornar apenas o caminho da cadeia de qualidade mais alta. Definir esse sinalizador retornará as cadeias de qualidade inferiores. Eles são retornados nos campos cLowerQualityChainContext e rgpLowerQualityChainContext do contexto da cadeia.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE 0x00000100	Definir esse sinalizador inibe a atualização automática de raízes de terceiros do Windows Update Web Server.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 0x08000000	Quando você define CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT e também especifica um valor para o dwUrlRetrievalTimeout membro da estrutura CERT_CHAIN_PARA, o valor especificado em dwUrlRetrievalTimeout representa o tempo limite cumulativo em todas as recuperações de URL de revogação. Se você definir CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT mas não especificar um valor dwUrlRetrievalTimeout , o tempo limite cumulativo máximo será definido, por padrão, como 20 segundos. Cada URL testada terá o tempo limite após a aprovação de metade do saldo cumulativo restante. Ou seja, a primeira URL atinge o tempo limite após 10 segundos, a segunda após 5 segundos, a terceira após 2,5 segundos e assim por diante até que uma URL seja bem-sucedida, 20 segundos se passaram ou não há mais URLs para testar. Se você não definir CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, cada URL de revogação na cadeia recebe um tempo limite máximo igual ao valor especificado em dwUrlRetrievalTimeout. Se você não especificar um valor para o membro dwUrlRetrievalTimeout, cada URL de revogação recebe um tempo limite padrão máximo de 15 segundos. Se nenhuma URL for bem-sucedida, o valor máximo de tempo limite cumulativo será de 15 segundos multiplicado pelo número de URLs na cadeia. Você pode definir os valores padrão usando a Política de Grupo.
CERT_CHAIN_TIMESTAMP_TIME 0x00000200	Quando esse sinalizador é definido, pTime é usado como a hora do carimbo de data/hora para determinar se o certificado final era válido. A hora atual também pode ser usada para determinar se o certificado final permanece válido. Todos os outros autoridade de certificação (AC) e certificados raiz na cadeia são verificados usando o horário atual e não pTime.
CERT_CHAIN_DISABLE_AIA 0x00002000	Definir esse sinalizador desativa explicitamente as recuperações do Acesso às Informações da Autoridade (AIA).

Você também pode definir os seguintes sinalizadores de revogação, mas apenas um sinalizador desse grupo pode ser definido por vez.

Valor	Significado
CERT_CHAIN_REVOCATION_CHECK_END_CERT 0x10000000	A verificação de revogação é feita no certificado final e somente no certificado final.
CERT_CHAIN_REVOCATION_CHECK_CHAIN 0x20000000	A verificação de revogação é feita em todos os certificados em cada cadeia.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT 0x40000000	A verificação de revogação é feita em todos os certificados em todas as cadeias, exceto no certificado raiz.

[in] pvReserved

Esse parâmetro é reservado e deve ser NULL.

[out] ppChainContext

O endereço de um ponteiro para o contexto de cadeia criado. Quando terminar de usar o contexto de cadeia, libere a cadeia chamando a função CertFreeCertificateChain.

Valor de retorno

Se a função for bem-sucedida, a função retornará diferente de zero (TRUE).

Se a função falhar, ela retornará zero (false). Para obter informações de erro estendidas, chame GetLastError.

Observações

Quando um aplicativo solicita uma cadeia de certificados, a estrutura retornada está na forma de um CERT_CHAIN_CONTEXT. Esse contexto contém uma matriz de estruturas de CERT_SIMPLE_CHAIN em que cada cadeia simples passa de um certificado final para um certificado autoassinado. O contexto de cadeia conecta cadeias simples por meio de listas de confiança. Cada cadeia simples contém a cadeia de certificados, informações de confiança resumida sobre a cadeia e informações de confiança sobre cada elemento de certificado na cadeia.

As seguintes observações se aplicam à verificação de assinatura forte:

Você pode habilitar a verificação de assinatura forte para essa função definindo o pStrongSignPara membro da estrutura de CERT_CHAIN_PARA que é apontado pelo parâmetro pChainPara.
Se um certificado sem uma assinatura forte for encontrado na cadeia, os erros de CERT_TRUST_HAS_WEAK_SIGNATURE e CERT_TRUST_IS_NOT_SIGNATURE_VALID serão definidos no campo dwErrorStatus da estrutura CERT_TRUST_STATUS. O parâmetro ppChainContext aponta para uma estrutura de CERT_CHAIN_CONTEXT que, por sua vez, aponta para a estrutura CERT_TRUST_STATUS.
Se a cadeia for forte assinada, a chave pública no certificado final será verificada para determinar se ela atende aos requisitos mínimos de comprimento de chave pública para uma assinatura forte. Se a condição não for atendida, os erros CERT_TRUST_HAS_WEAK_SIGNATURE e CERT_TRUST_IS_NOT_SIGNATURE_VALID serão definidos no campo dwErrorStatus da estrutura CERT_TRUST_STATUS. Para desabilitar a verificação do comprimento da chave, defina o valor CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG no dwStrongSignFlags membro da estrutura CERT_CHAIN_PARA apontada pelo parâmetro pChainPara.
Se os sinalizadores CERT_STRONG_SIGN_ENABLE_CRL_CHECK ou CERT_STRONG_SIGN_ENABLE_OCSP_CHECK forem definidos na estrutura CERT_STRONG_SIGN_SERIALIZED_INFO e uma resposta CRL ou OCSP for encontrada sem uma assinatura forte, a resposta CRL ou OCSP será tratada como offline. Ou seja, os erros CERT_TRUST_IS_OFFLINE_REVOCATION e CERT_TRUST_REVOCATION_STATUS_UNKNOWN são definidos no campo dwErrorStatus da estrutura de CERT_TRUST_STATUS. Além disso, o dwRevocationResult membro da estrutura CERT_REVOCATION_INFO está definido como NTE_BAD_ALGID.

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de Programa C: Criando uma cadeia de certificados.

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

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

Funções de verificação da cadeia de certificados

Compartilhar via