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 a hora para a 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 certificado específico 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 CRL ( lista de revogação de certificados ), 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 CTLs ( listas de confiança de certificado ). Esse parâmetro poderá ser NULL se nenhum repositório adicional for pesquisado.
[in] pChainPara
Um ponteiro para uma estrutura 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 |
|---|---|
|
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 precisaria ser verificado sempre que uma cadeia fosse criada para ele. |
|
A verificação de revogação acessa apenas URLs armazenadas em cache. |
|
Esse sinalizador é usado internamente durante a criação da cadeia para um certificado de signatário do protocolo OCSP (status certificado online) para evitar 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 de signatário OCSP. Esse sinalizador é usado durante essa segunda compilação 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. |
|
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.
Nota 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. |
|
Por motivos de desempenho, a segunda passagem de construção de cadeia considera apenas possíveis caminhos de cadeia que têm 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. |
|
Não há suporte para esse sinalizador. Os certificados no repositório "My" nunca são considerados para confiança de pares. |
|
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. |
|
Definir esse sinalizador indica que o chamador deseja aceitar verificações de assinatura fracas.
Esse sinalizador está disponível na atualização cumulativo de atualizações para cada sistema operacional começando com o Windows 7 e o Windows Server 2008 R2. |
|
O padrão é retornar apenas o caminho de cadeia de maior qualidade. Definir esse sinalizador retornará as cadeias de menor qualidade. Eles são retornados nos campos cLowerQualityChainContext e rgpLowerQualityChainContext do contexto da cadeia. |
|
Definir esse sinalizador inibe a atualização automática de raízes de terceiros do servidor Web Windows Update. |
|
Quando você define CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT e também especifica um valor para o membro dwUrlRetrievalTimeout 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 metade do saldo cumulativo restante ter passado. 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 tenham passado ou não haja 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 Política de Grupo. |
|
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. Todas as outras AC (autoridades de certificação ) e certificados raiz na cadeia são verificados usando a hora atual e não pTime. |
|
Definir esse sinalizador desativa explicitamente as recuperações do AIA (Acesso às Informações da Autoridade). |
Você também pode definir os sinalizadores de revogação a seguir, 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, solte a cadeia chamando a função CertFreeCertificateChain .
Valor retornado
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.
Comentários
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 CERT_SIMPLE_CHAIN em que cada cadeia simples vai 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 membro pStrongSignPara da estrutura CERT_CHAIN_PARA apontada 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 CERT_CHAIN_CONTEXT que, por sua vez, aponta para a estrutura CERT_TRUST_STATUS .
- Se a cadeia for fortemente 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 de 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 membro dwStrongSignFlags 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 de CERT_TRUST_IS_OFFLINE_REVOCATION e CERT_TRUST_REVOCATION_STATUS_UNKNOWN são definidos no campo dwErrorStatus da estrutura CERT_TRUST_STATUS . Além disso, o membro dwRevocationResult da estrutura CERT_REVOCATION_INFO é 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
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de