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

Article
02/26/2024

Spécifie le nom du sujet 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 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] SubjectName

Chaîne terminée par null qui contient le nom d’objet simple du certificat. Si le nom d’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 la fin null. Vous ne pouvez pas spécifier un 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 comme « name3, name2, name1 ».

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 de 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 à la valeur du paramètre StoreName .
CRYPT_E_NOT_FOUND	Un certificat correspondant au nom de l’objet est introuvable.
RPC_X_NULL_REF_POINTER	Le paramètre StoreName ou SubjectName ne peut pas être NULL.
BG_E_STRING_TOO_LONG	Le paramètre StoreName ou SubjectName 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).

La méthode utilise la chaîne de nom d’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 dans le magasin le premier certificat qui utilise le nom d’objet donné et qui 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 plutôt d’utiliser la méthode IBackgroundCopyJobHttpOptions ::SetClientCertificateByID .

Les identificateurs de certificat de carte à puce (empreintes numériques) ne sont pas pris en charge.

Exemples

L’exemple suivant montre comment spécifier un certificat client pour un travail à l’aide du nom d’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();
  }

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

Voir aussi

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions ::GetClientCertificate

IBackgroundCopyJobHttpOptions ::RemoveClientCertificate

IBackgroundCopyJobHttpOptions ::SetClientCertificateByID

Partager via