Método IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)
Especifica el identificador del certificado de cliente que se va a usar para la autenticación de cliente en una solicitud HTTPS (SSL).
Sintaxis
HRESULT SetClientCertificateByID(
[in] BG_CERT_STORE_LOCATION StoreLocation,
[in] LPCWSTR StoreName,
[in] byte *pCertHashBlob
);
Parámetros
[in] StoreLocation
Identifica la ubicación de un almacén del sistema que se va a usar para buscar el certificado. Para conocer los valores posibles, consulte la enumeración BG_CERT_STORE_LOCATION .
[in] StoreName
Cadena terminada en NULL que contiene el nombre del almacén de certificados. La cadena está limitada a 256 caracteres, incluido el terminador null. Puede especificar uno de los siguientes almacenes del sistema o un almacén definido por la aplicación. El almacén puede ser un almacén local o remoto.
| Valor | Significado |
|---|---|
|
Certificados de entidad de certificación |
|
Certificados personales |
|
Certificados raíz |
|
certificado del publicador de software |
[in] pCertHashBlob
Hash SHA1 que identifica el certificado. Use un búfer de 20 bytes para el hash. Para obtener más información, vea la sección Comentarios.
Valor devuelto
En la tabla siguiente se enumeran algunos de los posibles valores devueltos.
| Código devuelto | Descripción |
|---|---|
|
Correcto. |
|
El usuario no tiene permiso para acceder a la ubicación del almacén. |
|
El valor del parámetro StoreLocation no se define en la enumeración BG_CERT_STORE_LOCATION . |
|
No se encontró un almacén que coincida con el parámetro StoreName . |
|
No se encontró un certificado que coincida con el hash. |
|
El parámetro StoreName o pCertHashBlob no puede ser NULL. |
|
El tamaño del búfer pCertHashBlob no es de 20 bytes. |
|
El parámetro StoreName tiene más de 256 caracteres. |
|
El estado del trabajo no puede ser BG_JOB_STATE_CANCELLED ni BG_JOB_STATE_ACKNOWLEDGED. |
Comentarios
Solo el propietario del trabajo puede especificar el certificado de cliente. Si el trabajo cambia de propiedad, BITS quita el certificado del trabajo.
El certificado de cliente solo es aplicable a los archivos remotos que usan el protocolo HTTP o HTTPS. Puede especificar un certificado para todos los tipos de trabajo.
Cuando un sitio web acepta pero no requiere un certificado de cliente SSL y el trabajo de BITS no especifica un certificado de cliente, se producirá un error en el trabajo con ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).
Si crea un certificado para el trabajo o la aplicación, puede almacenar el identificador de certificado (huella digital) en el Registro o la base de datos y usarlo cuando un trabajo requiera un certificado. También puede enumerar los certificados en el almacén y permitir que el usuario elija el certificado. Otra alternativa es llamar a la función CertFindCertificateInStore para recuperar el contexto del certificado en función de algunos criterios. Con el contexto, llame a la función CertGetCertificateContextProperty para recuperar el hash (especifique CERT_HASH_PROP_ID para dwPropId).
No se admiten huellas digitales de Tarjeta inteligente.
Ejemplos
En el ejemplo siguiente se muestra cómo especificar un certificado de cliente para un trabajo mediante la huella digital del certificado. En el ejemplo se codifica la huella digital del certificado y se supone que pJob apunta a un trabajo 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Plataforma de destino | Windows |
| Encabezado | bits2_5.h (incluir Bits.h) |
| Library | Bits.lib |
Consulte también
IBackgroundCopyJobHttpOptions::GetClientCertificate