Método IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)
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 |
|---|---|
|
Certificados de autoridade de certificação |
|
Certificados pessoais |
|
Certificados raiz |
|
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 |
|---|---|
|
Êxito. |
|
O usuário não tem permissão para acessar o local da loja. |
|
O valor do parâmetro StoreLocation não é definido na enumeração BG_CERT_STORE_LOCATION . |
|
Não foi possível encontrar um repositório que corresponda ao parâmetro StoreName . |
|
Um certificado que corresponde ao hash não foi encontrado. |
|
O parâmetro StoreName ou pCertHashBlob não pode ser NULL. |
|
O tamanho do buffer pCertHashBlob não é de 20 bytes. |
|
O parâmetro StoreName tem mais de 256 caracteres. |
|
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 |
Confira também
IBackgroundCopyJobHttpOptions::GetClientCertificate