Funzione BCryptOpenAlgorithmProvider (bcrypt.h)

Articolo
07/16/2024

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. Può trattarsi di uno degli identificatori di algoritmo CNG standard o dell'identificatore per un altro algoritmo registrato.

[in] pszImplementation

Puntatore a una stringa Unicode con terminazione Null che identifica il provider specifico da caricare. Si tratta dell'alias registrato del provider primitivo di crittografia. 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 tutta la durata dell'handle, qualsiasi API crittografica BCrypt** userà il provider che è stato aperto correttamente.

Windows Server 2008 e Windows Vista: CNG tenta di eseguire il fallback al provider Microsoft CNG.

Di seguito sono riportati i nomi predefiniti dei provider.

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

[in] dwFlags

Flag che modificano il comportamento della funzione. 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 Hash-Based Message Authentication Code (HMAC) 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 di paging. Se questo flag non è presente, il provider viene caricato nel pool di memoria di paging. Quando si specifica 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 l'elaborazione delle operazioni successive sul provider a livello di dispatch. Se il provider non supporta la chiamata a livello di invio, verrà restituito un errore quando viene aperto usando questo flag. Windows Server 2008 e Windows Vista: Questo flag è supportato solo dai provider di algoritmi Microsoft e solo per gli algoritmi di hash e chiave simmetrica algoritmi di crittografia.
BCRYPT_HASH_REUSABLE_FLAG	Crea un oggetto hash 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 solo, quanto segue.

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

Osservazioni

A causa del numero e del tipo di operazioni necessarie per trovare, caricare e inizializzare un provider di algoritmi, la funzione BCryptOpenAlgorithmProvider è una funzione a elevato utilizzo di tempo. Per questo motivo, è consigliabile memorizzare nella cache tutti gli handle del provider di algoritmi che verranno usati più volte, anziché aprire e chiudere i provider di algoritmi oltre 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, 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, potrebbero richiedere un riavvio. Per questo motivo, è necessario riavviare prima di chiamare BCryptOpenAlgorithmProvider con qualsiasi provider appena configurato.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	bcrypt.h
libreria	Bcrypt.lib
dll	Bcrypt.dll

Vedere anche

BCryptCloseAlgorithmProvider

Condividi tramite