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

  • Artículo

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
CA
 Certificados de entidad de certificación
MI
 Certificados personales
RAÍZ
 Certificados raíz
SPC
 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
S_OK
 Correcto.
E_ACCESSDENIED
 El usuario no tiene permiso para acceder a la ubicación del almacén.
E_NOTIMPL
 El valor del parámetro StoreLocation no se define 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 parámetro StoreName .
CRYPT_E_NOT_FOUND
 No se encontró un certificado que coincida con el hash.
RPC_X_NULL_REF_POINTER
 El parámetro StoreName o pCertHashBlob no puede ser NULL.
RPC_X_BAD_STUB_DATA
 El tamaño del búfer pCertHashBlob no es de 20 bytes.
BG_E_STRING_TOO_LONG
 El parámetro StoreName 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).

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

IBackgroundCopyJobHttpOptions::GetClientCertificate

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByName