Metodo IBackgroundCopyJobHttpOptions::SetClientCertificateByName (bits2_5.h)

Articolo
03/14/2023

Specifica il nome soggetto del certificato client da usare per l'autenticazione client in una richiesta HTTPS (SSL).

Sintassi

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

Parametri

[in] StoreLocation

Identifica la posizione di un archivio di sistema da utilizzare per la ricerca del certificato. Per i valori possibili, vedere l'enumerazione BG_CERT_STORE_LOCATION .

[in] StoreName

Stringa con terminazione null contenente il nome dell'archivio certificati. La stringa è limitata a 256 caratteri, incluso il terminatore Null. È possibile specificare uno degli archivi di sistema seguenti o un archivio definito dall'applicazione. L'archivio può essere un archivio locale o remoto.

Valore	Significato
CA	Certificati dell'autorità di certificazione
MIO	Certificati personali
RADICE	Certificati radice
SPC	certificato di distribuzione del software

[in] SubjectName

Stringa con terminazione null contenente il nome del soggetto semplice del certificato. Se il nome soggetto contiene più nomi distinti relativi (RDN), è possibile specificare uno o più RDN adiacenti. Se si specificano più rdn, l'elenco è delimitato da virgole. La stringa è limitata a 256 caratteri, incluso il terminatore Null. Non è possibile specificare un nome soggetto vuoto.

Non includere l'identificatore dell'oggetto nel nome. È necessario specificare i nomi RDN nell'ordine inverso rispetto a quello visualizzato dal certificato. Ad esempio, se il nome soggetto nel certificato è "CN=name1, OU=name2, O=name3", specificare il nome soggetto come "name3, name2, name1".

Valore restituito

Nella tabella seguente sono elencati alcuni dei possibili valori restituiti.

Codice restituito	Descrizione
S_OK	Operazione completata.
E_ACCESSDENIED	L'utente non dispone dell'autorizzazione per accedere alla posizione dell'archivio.
E_NOTIMPL	Il valore per StoreLocation non è definito nell'enumerazione BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Impossibile trovare un archivio corrispondente al valore del parametro StoreName .
CRYPT_E_NOT_FOUND	Non è stato trovato un certificato corrispondente al nome dell'oggetto.
RPC_X_NULL_REF_POINTER	Il parametro StoreName o SubjectName non può essere NULL.
BG_E_STRING_TOO_LONG	Il parametro StoreName o SubjectName è superiore a 256 caratteri.
BG_E_INVALID_STATE	Lo stato del processo non può essere BG_JOB_STATE_CANCELLED o BG_JOB_STATE_ACKNOWLEDGED.

Commenti

Solo il proprietario del processo può specificare il certificato client. Se il processo cambia la proprietà, BITS rimuove il certificato dal processo.

Il certificato client è applicabile solo per i file remoti che usano il protocollo HTTP o HTTPS. È possibile specificare un certificato per tutti i tipi di processo.

Quando un sito Web accetta ma non richiede un certificato client SSL e il processo BITS non specifica un certificato client, il processo avrà esito negativo con ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).

Il metodo usa la stringa del nome soggetto per eseguire una ricerca sottostringa per il certificato. Poiché i nomi dei soggetti non sono necessariamente univoci, questo metodo cerca l'archivio per il primo certificato che usa il nome soggetto specificato ed è un certificato di autenticazione client. È consigliabile specificare il nome dell'oggetto completo per una migliore probabilità di trovare una singola corrispondenza. Se il certificato non è corretto (non attendibile), il processo avrà esito negativo BG_E_HTTP_ERROR_403 quando BITS tenta di trasferire il file e il processo verrà spostato nello stato di errore. Se non è possibile garantire un nome soggetto univoco, è consigliabile usare il metodo IBackgroundCopyJobHttpOptions::SetClientCertificateByID .

Gli identificatori di certificato SmartCard (identificazioni personali) non sono supportati.

Esempio

Nell'esempio seguente viene illustrato come specificare un certificato client per un processo usando il nome soggetto del certificato. L'esempio presuppone che pJob punti a un processo valido.


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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	bits2_5.h (includere Bits.h)
Libreria	Bits.lib