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

Article
02/26/2024

Spécifie l’identificateur du certificat client à utiliser pour l’authentification du client dans une requête HTTPS (SSL).

Syntaxe

HRESULT SetClientCertificateByID(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] byte                   *pCertHashBlob
);

Paramètres

[in] StoreLocation

Identifie l’emplacement d’un magasin système à utiliser pour rechercher le certificat. Pour connaître les valeurs possibles, consultez l’énumération BG_CERT_STORE_LOCATION .

[in] StoreName

Chaîne terminée par null qui contient le nom du magasin de certificats. La chaîne est limitée à 256 caractères, y compris la fin null. Vous pouvez spécifier l’un des magasins système suivants ou un magasin défini par l’application. Le magasin peut être un magasin local ou distant.

Valeur	Signification
Autorité de certification	Certificats d’autorité de certification
MON	Certificats personnels
RACINE	Certificats racines
SPC	certificat SPC (Software Publisher Certificate)

[in] pCertHashBlob

Hachage SHA1 qui identifie le certificat. Utilisez une mémoire tampon de 20 octets pour le hachage. Pour plus d'informations, consultez la section Notes.

Valeur retournée

Le tableau suivant répertorie certaines des valeurs de retour possibles.

Code de retour	Description
S_OK	Réussite.
E_ACCESSDENIED	L’utilisateur n’a pas l’autorisation d’accéder à l’emplacement du magasin.
E_NOTIMPL	La valeur du paramètre StoreLocation n’est pas définie dans l’énumération BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Impossible de trouver un magasin correspondant au paramètre StoreName .
CRYPT_E_NOT_FOUND	Un certificat correspondant au hachage est introuvable.
RPC_X_NULL_REF_POINTER	Le paramètre StoreName ou pCertHashBlob ne peut pas être NULL.
RPC_X_BAD_STUB_DATA	La taille de la mémoire tampon pCertHashBlob n’est pas de 20 octets.
BG_E_STRING_TOO_LONG	Le paramètre StoreName contient plus de 256 caractères.
BG_E_INVALID_STATE	L’état du travail ne peut pas être BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.

Remarques

Seul le propriétaire du travail peut spécifier le certificat client. Si le travail change de propriété, BITS supprime le certificat du travail.

Le certificat client s’applique uniquement aux fichiers distants qui utilisent le protocole HTTP ou HTTPS. Vous pouvez spécifier un certificat pour tous les types de travaux.

Lorsqu’un site web accepte mais n’a pas besoin d’un certificat client SSL et que le travail BITS ne spécifie pas de certificat client, le travail échoue avec ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).

Si vous créez un certificat pour le travail ou l’application, vous pouvez stocker l’identificateur de certificat (empreinte numérique) dans le registre ou la base de données et l’utiliser lorsqu’un travail nécessite un certificat. Vous pouvez également énumérer les certificats dans le magasin et laisser l’utilisateur choisir le certificat. Une autre alternative consiste à appeler la fonction CertFindCertificateInStore pour récupérer le contexte de certificat en fonction de certains critères. À l’aide du contexte, appelez la fonction CertGetCertificateContextProperty pour récupérer le hachage (spécifiez CERT_HASH_PROP_ID pour dwPropId).

Les empreintes numériques de carte à puce ne sont pas prises en charge.

Exemples

L’exemple suivant montre comment spécifier un certificat client pour un travail à l’aide de l’empreinte numérique du certificat. L’exemple code en dur l’empreinte numérique du certificat et suppose que pJob pointe vers un travail valide.


  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();
  }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	bits2_5.h (include Bits.h)
Bibliothèque	Bits.lib