IBackgroundCopyJobHttpOptions ::SetClientCertificateByID, méthode (bits2_5.h)

Spécifie l’identificateur du certificat client à utiliser pour l’authentification du client dans une demande 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 le terminateur 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.

[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.

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 ne nécessite pas de 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 de carte à puce ne sont pas prises en charge.

Examples

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

Spécifications

Voir aussi

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions ::GetClientCertificate

IBackgroundCopyJobHttpOptions ::RemoveClientCertificate

IBackgroundCopyJobHttpOptions ::SetClientCertificateByName