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.

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

[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

Consulte também

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

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