Função CertVerifyCertificateChainPolicy (wincrypt.h)

Artigo
08/15/2024

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 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 dwFlags membro da estrutura apontado 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 política de cadeia do Authenticode. O pvExtraPolicyPara membro da estrutura apontado por pPolicyPara pode ser definido para apontar para uma estrutura AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA. O pvExtraPolicyStatus membro da estrutura apontado 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 política de cadeia de carimbo de data/hora do Authenticode. O pvExtraPolicyPara membro da estrutura de dados apontado por pPolicyPara pode ser definido para apontar para uma estrutura AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA. O pvExtraPolicyStatus membro da estrutura de dados apontado por pPolicyStatus não é usado e deve ser definido como `NULL`.
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Implementa as verificações de política de cadeia de servidor/cliente SSL. O membro pvExtraPolicyPara na estrutura de dados apontado por pPolicyPara pode ser definido para apontar para uma estrutura de SSL_EXTRA_CERT_CHAIN_POLICY_PARA inicializada com critérios de política adicionais. Observação: Para diferenciar entre certificados de autorização de servidor e cliente, a chamada para a função CertGetCertificateChain para obter o contexto da 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 verificando se há uma szOID_BASIC_CONSTRAINTS ou uma extensão de szOID_BASIC_CONSTRAINTS2. Se nenhuma das extensões estiver presente, o certificado deverá ter 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 dwFlags membro da estrutura CERT_CHAIN_POLICY_PARA apontado 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 autoridade de certificação (AC). Se o PathLenConstraint estiver presente na extensão, ele será verificado. 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ão definidos 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 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 da cadeia, a AC que emitiu o certificado final, é uma AC confiável para a Autenticação do Windows NT. Uma AC é 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 definida no valor sinalizadores da política HKEY_LOCAL_MACHINE ProtectedRoots, definida por CERT_PROT_ROOT_FLAGS_REGPATH e a verificação 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 esse status de informações definido, 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 dwError membro da estrutura CERT_CHAIN_POLICY_STATUS apontada pelo parâmetro pPolicyStatus será definido como CERT_E_UNTRUSTEDROOT. O dwFlags membro da estrutura de CERT_CHAIN_POLICY_PARA apontado 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 verifique a raiz do aplicativo Microsoft "Autoridade de Certificação Raiz da Microsoft 2011". O dwFlags membro da estrutura de CERT_CHAIN_POLICY_PARA apontado 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 verifique as raízes de teste da Microsoft. Observação: Essa política identificador de objeto (OID) não executa nenhuma verificação de política por si só, ela deve ser usada 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 pvExtraPolicyStatus membro da estrutura CERT_CHAIN_POLICY_STATUS apontado pelo parâmetro pPolicyStatus deve apontar para SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS, que é atualizado com os resultados das verificações de conformidade de programas de criptografia e raiz fracos. Antes de chamar, o cbSize membro da estrutura de CERT_CHAIN_POLICY_STATUS apontado 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 na estrutura de CERT_CHAIN_POLICY_STATUS apontado 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 sem 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 de CERT_CHAIN_CONTEXT que contém uma cadeia a ser verificada.

[in] pPolicyPara

Um ponteiro para uma estrutura de CERT_CHAIN_POLICY_PARA que fornece os critérios de verificação de política para a cadeia. O dwFlags membro 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 pvExtraPolicyPara membro da estrutura.

[in, out] pPolicyStatus

Um ponteiro para uma estrutura CERT_CHAIN_POLICY_STATUS em que as informações de status na cadeia são retornadas. O status extra específico do OID pode ser retornado no pvExtraPolicyStatus membro dessa estrutura.

Valor de retorno

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

Se a cadeia puder ser verificada para a política especificada, será retornado e o dwError membro 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 de FALSE indica que a função não foi capaz de verificar a política.

Observações

Um dwError membro da estrutura CERT_CHAIN_POLICY_STATUS apontado 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 da cadeia, os lChainIndex e os membros lElementIndex da estrutura CERT_CHAIN_POLICY_STATUS serão definidos como . 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 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 verifica se os certificados na cadeia de certificados foram revogados.

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