Compartilhar via


Função CertGetCertificateChain (wincrypt.h)

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. Isso evitaria a recuperação de rede de CRLs ou OCSP para os certificados de autoridade de certificação ou final. CACHE_ONLY depende de um amigo no computador já ter recuperado a CRL ou OCSP da rede.
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: Não há suporte para esse valor.
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, como cabs CTL, raízes de terceiros e emissores de AIA. A maioria das raízes deve estar em um recurso crypt32.dll. Caso contrário, essa recuperação é necessária para evitar um erro de construção de cadeia. Esses cabs e raízes são hospedados em servidores CDN da Microsoft de alto desempenho.

Observação: Esse 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. Normalmente, os táxis CTL já são pré-buscados por meio do serviço cryptsvc.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 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 e 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). Às vezes, os servidores TLS são configurados incorretamente e não incluem os certificados de AC corretos no handshake.

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.

As seguintes recomendações se aplicariam a qualquer aplicativo do Windows que chame essas APIs para verificar um certificado de autenticação de servidor TLS:

  • Habilite apenas a verificação de revogação para o certificado final.
    • Defina CERT_CHAIN_REVOCATION_CHECK_END_CERT sinalizador.
    • A maioria dos certificados de AC tem CRLs com uma validade de tempo de 1 a 6 meses.
      • Como as CRLs baixadas são armazenadas em cache, essa validade é muito longa para ter muito valor.
    • Se houver um comprometimento de AC, os certificados também serão adicionados à CTL não permitida pelo Windows
    • A prática recomendada para servidores TLS é dar suporte à stapling OCSP para o certificado final.
      • Nesse caso, nenhuma recuperação de rede será necessária, a menos que a resposta OCSP grampeada tenha expirado.
  • Habilite as recuperações de rede para CRLs, OCSP, emissores do AIA e cabs CTL da plataforma Windows e raízes de terceiros.
    • Quando o CERT_CHAIN_REVOCATION_CHECK_END_CERT acima é definido, esse é o padrão.
    • Não defina nenhum dos sinalizadores a seguir para impedir recuperações de rede. Consulte a tabela dwFlags acima para obter mais informações sobre esses sinalizadores:
      • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
      • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
      • CERT_CHAIN_DISABLE_AIA
  • Habilite o tempo limite acumulado para recuperações de rede CRL e OCSP.
    • Defina o sinalizador de CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT passado para CertGetCertificateChain.
    • Fornece um limite superior sobre o tempo total permitido para recuperações de rede CRL e OCSP.
  • Reduza o tempo máximo permitido para cada recuperação de rede de 15 para 10 segundos.
    • Defina o campo dwUrlRetrievalTimeout no CERT_CHAIN_PARA passado para CertGetCertificateChain para 10 * 1000 milissegundos.
    • Isso também reduz o tempo limite acumulado de 20 para 10 segundos.
      • Somente as respostas OCSP devem ser baixadas para certificados finais. 5 segundos devem ser suficientes para esse download.
  • Ignorar erros de revogação offline.
    • Defina CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS no CERT_CHAIN_POLICY_PARA passado para CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
    • A recuperação de rede de OCSP e CRL é a melhor tentativa. A maioria das recuperações de rede deve ter êxito em alguns segundos, mas não é 100% garantida.
  • Informações de validação do certificado de fim de cache.
    • Defina o CERT_CHAIN_CACHE_END_CERT.
      • Habilita o cache LRU de informações sobre certificados finais, além de certificados intermediários.
    • É comum fazer várias conexões TLS com o mesmo servidor.

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