Método IBackgroundCopyJobHttpOptions::SetClientCertificateByName (bits2_5.h)
Especifica el nombre del firmante del certificado de cliente que se va a usar para la autenticación de cliente en una solicitud HTTPS (SSL).
Sintaxis
HRESULT SetClientCertificateByName(
[in] BG_CERT_STORE_LOCATION StoreLocation,
[in] LPCWSTR StoreName,
[in] LPCWSTR SubjectName
);
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] SubjectName
Cadena terminada en NULL que contiene el nombre de sujeto simple del certificado. Si el nombre del firmante contiene varios nombres distintivos relativos (RDN), puede especificar uno o varios RDN adyacentes. Si especifica más de un RDN, la lista está delimitada por comas. La cadena está limitada a 256 caracteres, incluido el terminador null. No se puede especificar un nombre de sujeto vacío.
No incluya el identificador de objeto en el nombre. Debe especificar los RDN en el orden inverso de lo que muestra el certificado. Por ejemplo, si el nombre del firmante del certificado es "CN=name1, OU=name2, O=name3", especifique el nombre del firmante como "name3, name2, name1".
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 de StoreLocation no está definido en la enumeración BG_CERT_STORE_LOCATION . |
|
No se encontró un almacén que coincida con el valor del parámetro StoreName . |
|
No se encontró un certificado que coincida con el nombre del firmante. |
|
El parámetro StoreName o SubjectName no puede ser NULL. |
|
El parámetro StoreName o SubjectName 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).
El método usa la cadena de nombre del firmante para realizar una búsqueda de subcadena para el certificado. Dado que los nombres de firmante no son necesariamente únicos, este método busca en el almacén el primer certificado que usa el nombre de sujeto especificado y es un certificado de autenticación de cliente. Debe proporcionar el nombre completo del firmante para obtener una mejor oportunidad de encontrar una sola coincidencia. Si el certificado no es correcto (no es de confianza), se producirá un error en el trabajo con BG_E_HTTP_ERROR_403 cuando BITS intente transferir el archivo y el trabajo se moverá al estado de error. Si no puede garantizar un nombre de sujeto único, considere la posibilidad de usar el método IBackgroundCopyJobHttpOptions::SetClientCertificateByID en su lugar.
No se admiten identificadores de certificado de Tarjeta inteligente (huellas digitales).
Ejemplos
En el ejemplo siguiente se muestra cómo especificar un certificado de cliente para un trabajo mediante el nombre del firmante del certificado. En el ejemplo se supone que pJob apunta a un trabajo 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
| 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