Funzione BCryptOpenAlgorithmProvider (bcrypt.h)

  • Articolo

La funzione BCryptOpenAlgorithmProvider carica e inizializza un provider CNG.

Sintassi

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

Parametri

[out] phAlgorithm

Puntatore a una variabile BCRYPT_ALG_HANDLE che riceve l'handle del provider CNG. Al termine dell'uso di questo handle, rilasciarlo passandolo alla funzione BCryptCloseAlgorithmProvider .

[in] pszAlgId

Puntatore a una stringa Unicode con terminazione null che identifica l'algoritmo di crittografia richiesto. Questo può essere uno degli identificatori di algoritmo CNG standard o l'identificatore per un altro algoritmo registrato.

[in] pszImplementation

Puntatore a una stringa Unicode con terminazione null che identifica il provider specifico da caricare. Questo è l'alias registrato del provider primitivo crittografico. Questo parametro è facoltativo e può essere NULL se non è necessario. Se questo parametro è NULL, verrà caricato il provider predefinito per l'algoritmo specificato.

Nota Se il valore del parametro pszImplementation è NULL, CNG tenta di aprire ogni provider registrato, in ordine di priorità, per l'algoritmo specificato dal parametro pszAlgId e restituisce l'handle del primo provider aperto correttamente. Per la durata dell'handle, tutte le API crittografiche BCrypt** useranno il provider aperto correttamente.
 
Windows Server 2008 e Windows Vista: CNG tenta di tornare al provider Microsoft CNG.

Di seguito sono riportati i nomi del provider predefiniti.

Valore Significato
MS_PRIMITIVE_PROVIDER
"Microsoft Primitive Provider"
 Identifica il provider Microsoft CNG di base.
MS_PLATFORM_CRYPTO_PROVIDER
L"Microsoft Platform Crypto Provider"
 Identifica il provider di archiviazione delle chiavi TPM fornito da Microsoft.

[in] dwFlags

Contrassegni che modificano il comportamento della funzione. Questo può essere zero o una combinazione di uno o più dei valori seguenti.

Valore Significato
BCRYPT_ALG_HANDLE_HMAC_FLAG
 Il provider eseguirà l'algoritmo HMAC ( Hash-Based Message Authentication Code ) con l'algoritmo hash specificato. Questo flag viene usato solo dai provider di algoritmi hash.
BCRYPT_PROV_DISPATCH
 Carica il provider nel pool di memoria non a pagina. Se questo flag non è presente, il provider viene caricato nel pool di memoria con pagina. Quando viene specificato questo flag, l'handle restituito non deve essere chiuso prima che tutti gli oggetti dipendenti siano stati liberati.
Nota Questo flag è supportato solo in modalità kernel e consente di elaborare le operazioni successive nel provider a livello di dispatch. Se il provider non supporta la chiamata a livello di invio, restituirà un errore quando si apre questo flag.
 
Windows Server 2008 e Windows Vista: Questo flag è supportato solo dai provider di algoritmi Microsoft e solo per algoritmi di hashing e algoritmi di crittografiaa chiave simmetrica.
BCRYPT_HASH_REUSABLE_FLAG
 Crea un oggetto hashing riutilizzabile. L'oggetto può essere usato per una nuova operazione di hashing immediatamente dopo aver chiamato BCryptFinishHash. Per altre informazioni, vedere Creazione di un hash con CNG.

Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Questo flag non è supportato.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non sono limitati a, i seguenti.

Codice restituito Descrizione
STATUS_SUCCESS
 La funzione ha avuto esito positivo.
STATUS_NOT_FOUND
 Nessun provider è stato trovato per l'ID dell'algoritmo specificato.
STATUS_INVALID_PARAMETER
 Uno o più parametri non sono validi.
STATUS_NO_MEMORY
 Si è verificato un errore di allocazione della memoria.

Commenti

A causa del numero e del tipo di operazioni necessarie per trovare, caricare e inizializzare un provider di algoritmi, la funzione BCryptOpenAlgorithmProvider è una funzione relativamente intensivo. A causa di questo, è consigliabile memorizzare nella cache qualsiasi provider di algoritmi che verrà usato più di una volta, anziché aprire e chiudere i provider di algoritmi su e oltre.

BCryptOpenAlgorithmProvider può essere chiamato dalla modalità utente o dalla modalità kernel. I chiamanti in modalità kernel devono essere in esecuzione in PASSIVE_LEVELIRQL.

Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte del Driver Development Kit (DDK). Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.

A partire da Windows 10, il CNG non segue più ogni aggiornamento alla configurazione della crittografia. Alcune modifiche, ad esempio l'aggiunta di un nuovo provider predefinito o la modifica dell'ordine di preferenza dei provider di algoritmi, possono richiedere un riavvio. A causa di questo, è necessario riavviare prima di chiamare BCryptOpenAlgorithmProvider con qualsiasi provider appena configurato.

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione bcrypt.h
Libreria Bcrypt.lib
DLL Bcrypt.dll

Vedi anche

BCryptCloseAlgorithmProvider