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

Artículo
08/22/2023

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
CA	Certificados de entidad de certificación
MI	Certificados personales
RAÍZ	Certificados raíz
SPC	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
S_OK	Correcto.
E_ACCESSDENIED	El usuario no tiene permiso para acceder a la ubicación del almacén.
E_NOTIMPL	El valor de StoreLocation no está definido en la enumeración BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	No se encontró un almacén que coincida con el valor del parámetro StoreName .
CRYPT_E_NOT_FOUND	No se encontró un certificado que coincida con el nombre del firmante.
RPC_X_NULL_REF_POINTER	El parámetro StoreName o SubjectName no puede ser NULL.
BG_E_STRING_TOO_LONG	El parámetro StoreName o SubjectName tiene más de 256 caracteres.
BG_E_INVALID_STATE	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