Método IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate (bits10_3.h)

Um método de retorno de chamada que você implementa que será chamado para que você possa validar os certificados de servidor enviados quando uma conexão HTTPS for aberta.

Sintaxe

HRESULT ValidateServerCertificate(
  IBackgroundCopyJob  *job,
  IBackgroundCopyFile *file,
  DWORD               certLength,
  const BYTE []       certData,
  DWORD               certEncodingType,
  DWORD               certStoreLength,
  const BYTE []       certStoreData
);

Parâmetros

job

Tipo: IBackgroundCopyJob*

O trabalho.

file

Tipo: IBackgroundCopyFile*

O arquivo que está sendo transferido.

certLength

Tipo: DWORD

O comprimento em bytes dos dados do certificado.

certData

Tipo: const BYTE []

Uma matriz de bytes que contém os dados do certificado. O número de bytes deve corresponder certLengtha .

certEncodingType

Tipo: DWORD

O tipo de codificação de certificado.

certStoreLength

Tipo: DWORD

O comprimento em bytes dos dados do repositório de certificados.

certStoreData

Tipo: const BYTE []

Uma matriz de bytes que contém os dados do repositório de certificados. O número de bytes deve corresponder certStoreLengtha .

Retornar valor

Retorne S_OK para indicar que o certificado é aceitável. Caso contrário, retorne qualquer código de erroHRESULT para indicar que o certificado não é aceitável.

Comentários

A validação do certificado é executada em duas fases. A primeira fase é a fase do so (sistema operacional) em que o sistema operacional executa um conjunto padrão de verificações de validação no certificado. Depois disso, se a fase do sistema operacional passar o certificado, o retorno de chamada será chamado para executar uma validação adicional.

Implemente esse método de validação quando quiser executar suas próprias verificações no certificado do servidor. Suas próprias verificações são adicionais às verificações normais de validação de certificado do sistema operacional.

Se o método de validação recusar o certificado, o trabalho fará a transição para BG_JOB_STATE_TRANSIENT_ERROR com um contexto de erro de trabalho de BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK e o erro HRESULT do retorno de chamada. Se o retorno de chamada não puder ser chamado (por exemplo, porque o BITS precisava validar um certificado do servidor após a saída do programa), o código de erro do trabalho será BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Quando o aplicativo for executado na próxima vez, ele poderá corrigir esse erro definindo o retorno de chamada de validação novamente e retomando o trabalho.

O BITS chamará esse método de retorno de chamada somente se você implementar a interface IBackgroundCopyServerCertificateValidationCallback e passá-la para IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface.

A interface de validação se torna inválida quando o aplicativo é encerrado; O BITS não mantém um registro da interface de validação. Como resultado, o processo de inicialização do aplicativo deve chamar SetServerCertificateValidationInterface nesses trabalhos existentes para os quais você deseja receber solicitações de validação de certificado.

Se mais de um aplicativo chamar SetServerCertificateValidationInterface para definir a interface de notificação para o trabalho, o último aplicativo a chamá-lo será aquele que receberá notificações. Os outros aplicativos não receberão notificações.

Aqui estão as etapas gerais para validar um certificado. Lembre-se de que essas etapas são apenas um exemplo. A validação real está sob seu controle. Além disso, as etapas 5 a 7 são praticamente as mesmas que o sistema operacional faz durante a etapa de validação do sistema operacional.

1. Chame CertCreateCertificateContext com certEncodingType, certDatae certLength para recuperar um CERT_CONTEXT.

2. Declare e inicialize uma estrutura de CRYPT_DATA_BLOB (definida em wincrypt.h) com o blob de memória serializado passado por e certStoreLengthcertStoreData.

DATA_BLOB storeData{};
storeData.cbData = certStoreLength;
storeData.pbData = const_cast<PBYTE>(certStoreData);

3. Obtenha um identificador para a cadeia de certificados chamando CertOpenStore com CERT_STORE_PROV_SERIALIZED, 0, nullptr, flags e um ponteiro para o CRYPT_DATA_BLOB da etapa 2.
4. Obtenha um ponteiro para um contexto de cadeia de certificados chamando CertGetCertificateChain com nullptr, certContext, nullptr, o identificador da etapa 3, parâmetros de cadeia, sinalizadores e nullptr.
5. Crie a política de validação de certificado.

CERT_CHAIN_POLICY_PARA policyParams{};
policyParams.cbSize = sizeof(policyParams);
policyParams.dwFlags =
    CERT_CHAIN_POLICY_IGNORE_NOT_TIME_VALID_FLAG |
    CERT_CHAIN_POLICY_IGNORE_WRONG_USAGE_FLAG |
    CERT_CHAIN_POLICY_IGNORE_INVALID_NAME_FLAG |
    CERT_CHAIN_POLICY_ALLOW_UNKNOWN_CA_FLAG;

6. Chame CertVerifyCertificateChainPolicy com tipo de política, contexto de cadeia, parâmetros de política e status de política.
7. Converta o erro Win32 (policyStatus.dwError) em um HRESULT e retorne-o.

Segue-se uma descrição dos comportamentos de cache de validação do BITS. O BITS mantém um cache por trabalho de certificados que passaram pela validação personalizada. Isso é para evitar a validação redundante e potencialmente cara durante o tempo de vida do trabalho. O cache consiste em ponto de extremidade do <servidor, tuplas de hash> de certificado, em que o ponto de extremidade é definido como nome do servidor:porta. Se um trabalho já tiver permitido um certificado específico de um ponto de extremidade específico, o retorno de chamada não será chamado novamente.

É claro que o certificado terá que passar pela lógica de validação do sistema operacional em cada tentativa de conexão (você pode personalizar a lógica de validação do sistema operacional com uma chamada para IBackgroundCopyJobHttpOptions::SetSecurityFlags), que aborda casos de canto sensíveis ao tempo, como quando o certificado foi válido muito recentemente (em termos de segundos), mas expirou agora.

O BITS não armazena em cache certificados considerados inválidos pelo retorno de chamada de validação fornecido pelo aplicativo. É importante que você esteja ciente de todas as tentativas de conexão malsucedidas, para que possa detectar implantações mal-intencionadas no nível do aplicativo. Por exemplo, um certificado único incorreto é muito menos preocupante do que milhares de certificados inválidos do mesmo servidor.

O cache de certificados de um trabalho é limpo em cada chamada para SetServerCertificateValidationInterface, pois indica que a lógica de validação de certificado do servidor do aplicativo foi alterada.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 1809 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2016 [somente aplicativos da área de trabalho]
Cabeçalho	bits10_3.h (inclua Bits.h)
Biblioteca	Bits.lib
DLL	Bits.dll

Confira também

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface