Método IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)

Artigo
02/23/2024

Especifica o identificador do certificado do cliente a ser usado para autenticação de cliente em uma solicitação HTTPS (SSL).

Sintaxe

HRESULT SetClientCertificateByID(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] byte                   *pCertHashBlob
);

Parâmetros

[in] StoreLocation

Identifica o local de um repositório do sistema a ser usado para procurar o certificado. Para obter valores possíveis, consulte a enumeração BG_CERT_STORE_LOCATION .

[in] StoreName

Cadeia de caracteres terminada em nulo que contém o nome do repositório de certificados. A cadeia de caracteres é limitada a 256 caracteres, incluindo o terminador nulo. Você pode especificar um dos seguintes repositórios do sistema ou um repositório definido pelo aplicativo. O repositório pode ser um repositório local ou remoto.

Valor	Significado
CA	Certificados de autoridade de certificação
MEU	Certificados pessoais
RAIZ	Certificados raiz
SPC	Certificado do Fornecedor do Software

[in] pCertHashBlob

Hash SHA1 que identifica o certificado. Use um buffer de 20 bytes para o hash. Para obter mais informações, consulte Comentários.

Retornar valor

A tabela a seguir lista alguns dos valores retornados possíveis.

Código de retorno	Descrição
S_OK	Êxito.
E_ACCESSDENIED	O usuário não tem permissão para acessar o local da loja.
E_NOTIMPL	O valor do parâmetro StoreLocation não é definido na enumeração BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Não foi possível encontrar um repositório que corresponda ao parâmetro StoreName .
CRYPT_E_NOT_FOUND	Um certificado que corresponde ao hash não foi encontrado.
RPC_X_NULL_REF_POINTER	O parâmetro StoreName ou pCertHashBlob não pode ser NULL.
RPC_X_BAD_STUB_DATA	O tamanho do buffer pCertHashBlob não é de 20 bytes.
BG_E_STRING_TOO_LONG	O parâmetro StoreName tem mais de 256 caracteres.
BG_E_INVALID_STATE	O estado do trabalho não pode ser BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.

Comentários

Somente o proprietário do trabalho pode especificar o certificado do cliente. Se o trabalho alterar a propriedade, o BITS removerá o certificado do trabalho.

O certificado do cliente é aplicável somente a arquivos remotos que usam o protocolo HTTP ou HTTPS. Você pode especificar um certificado para todos os tipos de trabalho.

Quando um site aceita, mas não requer um certificado de cliente SSL, e o trabalho BITS não especifica um certificado de cliente, o trabalho falhará com ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).

Se você criar um certificado para o trabalho ou aplicativo, poderá armazenar o identificador de certificado (impressão digital) no registro ou no banco de dados e usá-lo quando um trabalho exigir um certificado. Você também pode enumerar os certificados no repositório e permitir que o usuário escolha o certificado. Outra alternativa é chamar a função CertFindCertificateInStore para recuperar o contexto do certificado com base em alguns critérios. Usando o contexto, chame a função CertGetCertificateContextProperty para recuperar o hash (especifique CERT_HASH_PROP_ID para dwPropId).

Não há suporte para impressões digitais smartcard.

Exemplos

O exemplo a seguir mostra como especificar um certificado de cliente para um trabalho usando a impressão digital do certificado. O exemplo codifica a impressão digital do certificado e pressupõe que pJob aponta para um trabalho válido.


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;  
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;
  BYTE Thumbprint[] = {0xa1, 0x06, 0x6e, 0x13, 0xf2, 0x34, 0x49, 0x0a, 0x22, 0xd7, 0x6f, 0xb2, 0x80, 0xab, 0x68, 0x7d, 0x16, 0x55, 0xb3, 0x14};


  // Retrieve a pointer to the IBackgroundCopyJob4 interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"QueryInterface for HttpOptions failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByID(BG_CERT_STORE_LOCATION_CURRENT_USER, 
      L"MY", Thumbprint);
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByID failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	bits2_5.h (inclua Bits.h)
Biblioteca	Bits.lib