Metodo IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)

Articolo
03/14/2023

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

Sintassi

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

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 carattere di terminazione 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] pCertHashBlob

Hash SHA1 che identifica il certificato. Usare un buffer a 20 byte per l'hash. Per altre informazioni, vedere la sezione Osservazioni.

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 il parametro StoreLocation non è definito nell'enumerazione BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Impossibile trovare un archivio corrispondente al parametro StoreName .
CRYPT_E_NOT_FOUND	Non è stato trovato un certificato corrispondente all'hash.
RPC_X_NULL_REF_POINTER	Il parametro StoreName o pCertHashBlob non può essere NULL.
RPC_X_BAD_STUB_DATA	La dimensione del buffer pCertHashBlob non è di 20 byte.
BG_E_STRING_TOO_LONG	Il parametro StoreName è costituito da più di 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 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).

Se si crea un certificato per il processo o l'applicazione, è possibile archiviare l'identificatore del certificato (identificazione personale) nel Registro di sistema o nel database e usarlo quando un processo richiede un certificato. È anche possibile enumerare i certificati nell'archivio e consentire all'utente di scegliere il certificato. Un'altra alternativa consiste nel chiamare la funzione CertFindCertificateInStore per recuperare il contesto del certificato in base ad alcuni criteri. Usando il contesto, chiamare la funzione CertGetCertificateContextProperty per recuperare l'hash (specificare CERT_HASH_PROP_ID per dwPropId).

Le identificazioni personali della smart card non sono supportate.

Esempio

Nell'esempio seguente viene illustrato come specificare un certificato client per un processo usando l'identificazione personale del certificato. L'esempio imposta come hardcoded l'identificazione personale del certificato e presuppone che pJob punti a un processo valido.


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

Requisiti

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