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_CERT0x00000001 |
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_ONLY0x80000000 |
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_CERT0x04000000 |
Esse sinalizador é usado internamente durante a criação da cadeia para um certificado de protocolo de status de certificado online Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL0x00000004 |
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_TRUST0x00000800 |
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_TRUST0x00000400 |
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 Windows Server 2003 e Windows XP: Não há suporte para esse sinalizador. |
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE0x00010000 |
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_CONTEXTS0x00000080 |
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_UPDATE0x00000100 |
Definir esse sinalizador inibe a atualização automática de raízes de terceiros do Windows Update Web Server. |
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT0x08000000 |
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 Você pode definir os valores padrão usando a Política de Grupo. |
CERT_CHAIN_TIMESTAMP_TIME0x00000200 |
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_AIA0x00002000 |
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_CERT0x10000000 |
A verificação de revogação é feita no certificado final e somente no certificado final. |
CERT_CHAIN_REVOCATION_CHECK_CHAIN0x20000000 |
A verificação de revogação é feita em todos os certificados em cada cadeia. |
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT0x40000000 |
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 eCERT_TRUST_IS_NOT_SIGNATURE_VALID serão definidos no campodwErrorStatus da estrutura CERT_TRUST_STATUS . O parâmetro ppChainContextaponta para uma estrutura de CERT_CHAIN_CONTEXT que, por sua vez, aponta para a estruturaCERT_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 eCERT_TRUST_IS_NOT_SIGNATURE_VALID serão definidos no campodwErrorStatus 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 eCERT_TRUST_REVOCATION_STATUS_UNKNOWN são definidos no campo dwErrorStatusda 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 paraCertGetCertificateChain 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.
- Defina o campo dwUrlRetrievalTimeout
- 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.
- Defina o CERT_CHAIN_CACHE_END_CERT.
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 |