Função CertVerifyCertificateChainPolicy (wincrypt.h)

Artigo
08/27/2023

A função CertVerifyCertificateChainPolicy verifica uma cadeia de certificados para verificar sua validade, incluindo sua conformidade com quaisquer critérios de política de validade especificados.

Sintaxe

BOOL CertVerifyCertificateChainPolicy(
  [in]      LPCSTR                    pszPolicyOID,
  [in]      PCCERT_CHAIN_CONTEXT      pChainContext,
  [in]      PCERT_CHAIN_POLICY_PARA   pPolicyPara,
  [in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);

Parâmetros

[in] pszPolicyOID

As estruturas de política de cadeia de verificação predefinidas atuais estão listadas na tabela a seguir.

Valor	Significado
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	Implementa as verificações de política de cadeia de base. O membro dwFlags da estrutura apontada por pPolicyPara pode ser definido para alterar o comportamento de verificação de política padrão.
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	Implementa as verificações de verificação da política de cadeia de autenticação. O membro pvExtraPolicyPara da estrutura apontada por pPolicyPara pode ser definido para apontar para uma estrutura AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA . O membro pvExtraPolicyStatus da estrutura apontada por pPolicyStatus pode ser definido para apontar para uma estrutura AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS .
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	Implementa verificações de verificação de política de cadeia de carimbo de data/hora do Authenticode. O membro pvExtraPolicyPara da estrutura de dados apontada por pPolicyPara pode ser definido para apontar para uma estrutura AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA . O membro pvExtraPolicyStatus da estrutura de dados apontada por pPolicyStatus não é usado e deve ser definido como NULL
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Implementa as verificações de verificação de política de cadeia de servidor/cliente SSL. O membro pvExtraPolicyPara na estrutura de dados apontada por pPolicyPara pode ser definido para apontar para uma estrutura SSL_EXTRA_CERT_CHAIN_POLICY_PARA inicializada com critérios de política adicionais. Nota Para diferenciar entre certificados de autorização de servidor e cliente, a chamada para a função CertGetCertificateChain para obter o contexto de cadeia deve especificar o tipo de certificado definindo o uso esperado. Defina o uso esperado definindo o membro RequestedUsage da estrutura CERT_CHAIN_PARA passada no parâmetro de entrada pChainPara da função CertGetCertificateChain .
CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5	Implementa a política de cadeia de restrições básica. Itera todos os certificados na cadeia de verificação de uma szOID_BASIC_CONSTRAINTS ou uma extensão de szOID_BASIC_CONSTRAINTS2. Se nenhuma das extensões estiver presente, presume-se que o certificado tenha uma política válida. Caso contrário, para o primeiro elemento de certificado, verifica se ele corresponde ao CA_FLAG esperado ou END_ENTITY_FLAG especificado no membro dwFlags da estrutura CERT_CHAIN_POLICY_PARA apontada pelo parâmetro pPolicyPara . Se nenhum dos dois sinalizadores estiver definido, o primeiro elemento poderá ser uma AC ou END_ENTITY. Todos os outros elementos devem ser uma AC (autoridade de certificação ). Se PathLenConstraint estiver presente na extensão, ela será verificada. Os primeiros elementos nas cadeias simples restantes (ou seja, os certificados usados para assinar a CTL) são verificados como sendo um END_ENTITY. Se essa verificação falhar, dwError será definido como TRUST_E_BASIC_CONSTRAINTS.
CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6	Implementa a política de cadeia de autenticação do Windows NT, que consiste em três verificações de cadeia distintas na seguinte ordem: CERT_CHAIN_POLICY_BASE – implementa as verificações de verificação de política de cadeia de base. O LOWORD de dwFlags pode ser definido em pPolicyPara para alterar o comportamento de verificação de política padrão. Para obter mais informações, consulte CERT_CHAIN_POLICY_BASE. CERT_CHAIN_POLICY_BASIC_CONSTRAINTS – implementa a política de cadeia de restrições básica. O HIWORD de dwFlags pode ser definido para especificar se o primeiro elemento deve ser uma AC ou END_ENTITY. Para obter mais informações, consulte CERT_CHAIN_POLICY_BASIC_CONSTRAINTS. Verifica se o segundo elemento na cadeia, a AC que emitiu o certificado final, é uma AC confiável para a Autenticação do Windows NT. Uma AC será considerada confiável se existir no repositório de registro do sistema "NTAuth" encontrado no local do repositório CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE. Se essa verificação falhar, a AC não será confiável e dwError será definido como CERT_E_UNTRUSTEDCA. Se CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG estiver definido no valor Flags da subchave da política de HKEY_LOCAL_MACHINEProtectedRoots, definida por CERT_PROT_ROOT_FLAGS_REGPATH e a marcar acima falhar, a cadeia será verificada para CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS definida em dwInfoStatus. Isso será definido se houver uma restrição de nome válida para todos os namespaces, incluindo UPN. Se a cadeia não tiver essas informações status definidas, dwError será definido como CERT_E_UNTRUSTEDCA.
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	Verifica o último elemento da primeira cadeia simples para uma chave pública raiz da Microsoft. Se esse elemento não contiver uma chave pública raiz da Microsoft, o membro dwError da estrutura CERT_CHAIN_POLICY_STATUS apontada pelo parâmetro pPolicyStatus será definido como CERT_E_UNTRUSTEDROOT. O membro dwFlags da estrutura CERT_CHAIN_POLICY_PARA apontada pelo parâmetro pPolicyStatus pode conter o sinalizador MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG, o que faz com que essa função marcar para a raiz do aplicativo microsoft "Microsoft Root Certificate Authority 2011". O membro dwFlags da estrutura CERT_CHAIN_POLICY_PARA apontada pelo parâmetro pPolicyPara pode conter o sinalizador MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG, o que faz com que essa função também marcar para as raízes de teste da Microsoft. Nota Esse OID ( identificador de objeto de política) não executa nenhuma verificação de política por si só, ele deve ser usado em conjunto com outras políticas.
CERT_CHAIN_POLICY_EV (LPCSTR) 8	Especifica que a validação estendida de certificados é executada. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor.
CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9	Verifica se algum certificado na cadeia tem uma criptografia fraca ou se a conformidade do certificado raiz de terceiros e fornece uma cadeia de caracteres de erro. O membro pvExtraPolicyStatus da estrutura CERT_CHAIN_POLICY_STATUS apontada pelo parâmetro pPolicyStatus deve apontar para SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS, que é atualizada com os resultados das fracas verificações de conformidade do programa de criptografia e raiz. Antes de chamar, o membro cbSize da estrutura CERT_CHAIN_POLICY_STATUS apontada pelo parâmetro pPolicyStatus deve ser definido como um valor maior ou igual a sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS). O membro dwError em CERT_CHAIN_POLICY_STATUS estrutura apontada pelo parâmetro pPolicyStatus será definido como TRUST_E_CERT_SIGNATURE para uma possível criptografia fraca e definido como CERT_E_UNTRUSTEDROOT para Raízes de Terceiros não em conformidade com o Programa Raiz da Microsoft. Windows 10, versão 1607, Windows Server 2016, Windows 10, versão 1511 com KB3172985, Windows 10 RTM com KB3163912, Windows 8.1 e Windows Server 2012 R2 com KB3163912 e Windows 7 com SP1 e Windows Server 2008 R2 SP1 com KB3161029

[in] pChainContext

Um ponteiro para uma estrutura CERT_CHAIN_CONTEXT que contém uma cadeia a ser verificada.

[in] pPolicyPara

Um ponteiro para uma estrutura CERT_CHAIN_POLICY_PARA que fornece os critérios de verificação de política para a cadeia. O membro dwFlags dessa estrutura pode ser definido para alterar o comportamento de verificação de política padrão.

Além disso, parâmetros específicos da política também podem ser passados no membro pvExtraPolicyPara da estrutura.

[in, out] pPolicyStatus

Um ponteiro para uma estrutura CERT_CHAIN_POLICY_STATUS em que status informações sobre a cadeia são retornadas. As status extras específicas do OID podem ser retornadas no membro pvExtraPolicyStatus dessa estrutura.

Valor retornado

O valor retornado indica se a função foi capaz de marcar para a política, não indica se a política marcar falhou ou passou.

Se a cadeia puder ser verificada para a política especificada, TRUE será retornado e o membro dwError do pPolicyStatus será atualizado. Um dwError de 0 (ERROR_SUCCESS ou S_OK) indica que a cadeia atende à política especificada.

Se a cadeia não puder ser validada, o valor retornado será TRUE e você precisará verificar o parâmetro pPolicyStatus para o erro real.

Um valor false indica que a função não foi capaz de marcar para a política.

Comentários

Um membro dwError da estrutura de CERT_CHAIN_POLICY_STATUS apontada por pPolicyStatus pode se aplicar a um único elemento de cadeia, a uma cadeia simples ou a um contexto de cadeia inteiro. Se dwError se aplicar a todo o contexto de cadeia, os membros lChainIndex e lElementIndex da estrutura CERT_CHAIN_POLICY_STATUS serão definidos como –1. Se dwError se aplicar a uma cadeia simples completa, lElementIndex será definido como –1 e lChainIndex será definido como o índice da primeira cadeia que tem um erro. Se dwError se aplicar a um único elemento de certificado, lChainIndex e lElementIndex indexarão o primeiro certificado com o erro.

Para obter o elemento de certificado, use esta sintaxe:

pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];

Use a função CertGetCertificateChain para habilitar e executar a verificação de revogação de certificado. A função CertVerifyCertificateChainPolicy não marcar se os certificados na cadeia de certificados forem revogados.

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