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

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

Sintaxe

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

Parâmetros

[in] StoreLocation

Identifica o local de um repositório do sistema a ser usado para procurar o certificado. Para obter os 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 de sistema ou um repositório definido pelo aplicativo. O repositório pode ser um repositório local ou remoto.

[in] SubjectName

Cadeia de caracteres terminada em nulo que contém o nome da entidade simples do certificado. Se o nome da entidade contiver vários RDNs (nomes distintos relativos), você poderá especificar um ou mais RDNs adjacentes. Se você especificar mais de um RDN, a lista será delimitada por vírgulas. A cadeia de caracteres é limitada a 256 caracteres, incluindo o terminador nulo. Não é possível especificar um nome de assunto vazio.

Não inclua o identificador de objeto no nome. Você deve especificar os RDNs na ordem inversa do que o certificado exibe. Por exemplo, se o nome da entidade no certificado for "CN=name1, OU=name2, O=name3", especifique o nome da entidade como "name3, name2, name1".

Retornar valor

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

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).

O método usa a cadeia de caracteres de nome da entidade para executar uma pesquisa de subcadeia de caracteres para o certificado. Como os nomes de entidade não são necessariamente exclusivos, esse método pesquisa no repositório o primeiro certificado que usa o nome da entidade fornecido e é um certificado de autenticação de cliente. Você deve fornecer o nome completo do assunto para ter mais chances de encontrar uma única correspondência. Se o certificado não estiver correto (não confiável), o trabalho falhará com BG_E_HTTP_ERROR_403 quando o BITS tentar transferir o arquivo e o trabalho for movido para o estado de erro. Se você não puder garantir um nome de assunto exclusivo, considere usar o método IBackgroundCopyJobHttpOptions::SetClientCertificateByID .

Não há suporte para identificadores de certificado SmartCard (impressões digitais).

Exemplos

O exemplo a seguir mostra como especificar um certificado de cliente para um trabalho usando o nome da entidade do certificado. O exemplo pressupõe que pJob aponta para um trabalho válido.

  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;

  // Change list of names to actual list of names.
  LPWSTR pSubjectName = L"name3, name2, name1";  
                                                    
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

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


cleanup:

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

Requisitos

Confira também

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions::GetClientCertificate

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByID