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

Spécifie le nom d’objet du certificat client à utiliser pour l’authentification du client dans une demande HTTPS (SSL).

Syntaxe

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

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] SubjectName

Chaîne terminée par null qui contient le nom d’objet simple du certificat. Si le nom de l’objet contient plusieurs noms uniques relatifs (RDN), vous pouvez spécifier un ou plusieurs RDN adjacents. Si vous spécifiez plusieurs RDN, la liste est délimitée par des virgules. La chaîne est limitée à 256 caractères, y compris le terminateur Null. Vous ne pouvez pas spécifier de nom d’objet vide.

N’incluez pas l’identificateur d’objet dans le nom. Vous devez spécifier les RDN dans l’ordre inverse de ce que le certificat affiche. Par exemple, si le nom de l’objet dans le certificat est « CN=name1, OU=name2, O=name3 », spécifiez le nom de l’objet « name3, name2, name1 ».

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

La méthode utilise la chaîne de nom de l’objet pour effectuer une recherche de sous-chaîne pour le certificat. Étant donné que les noms d’objet ne sont pas nécessairement uniques, cette méthode recherche le magasin pour le premier certificat qui utilise le nom de l’objet donné et est un certificat d’authentification client. Vous devez fournir le nom complet de l’objet pour une meilleure chance de trouver une correspondance unique. Si le certificat n’est pas correct (non approuvé), le travail échoue avec BG_E_HTTP_ERROR_403 lorsque BITS tente de transférer le fichier et que le travail passe à l’état d’erreur. Si vous ne pouvez pas garantir un nom d’objet unique, envisagez d’utiliser la méthode IBackgroundCopyJobHttpOptions ::SetClientCertificateByID à la place.

Les identificateurs de certificat smartCard (empreintes) ne sont pas pris en charge.

Examples

L’exemple suivant montre comment spécifier un certificat client pour un travail à l’aide du nom de l’objet du certificat. L’exemple suppose que pJob pointe vers un travail valide.

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

Spécifications

Voir aussi

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions ::GetClientCertificate

IBackgroundCopyJobHttpOptions ::RemoveClientCertificate

IBackgroundCopyJobHttpOptions ::SetClientCertificateByID