BCryptOpenAlgorithmProvider-Funktion (bcrypt.h)

Die Funktion BCryptOpenAlgorithmProvider lädt und initialisiert einen CNG-Anbieter.

Syntax

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

Parameter

[out] phAlgorithm

Ein Zeiger auf eine BCRYPT_ALG_HANDLE Variable, die das Handle des CNG-Anbieters empfängt. Wenn Sie die Verwendung dieses Handles abgeschlossen haben, geben Sie es frei, indem Sie es an die Funktion BCryptCloseAlgorithmProvider übergeben.

[in] pszAlgId

Ein Zeiger auf eine unicode-Zeichenfolge mit NULL-Beendigung, die den angeforderten kryptografischen Algorithmus identifiziert. Dies kann einer der Standardmäßigen CNG-Algorithmusbezeichner oder der Bezeichner für einen anderen registrierten Algorithmus sein.

[in] pszImplementation

Ein Zeiger auf eine unicode-Zeichenfolge mit Null-Beendigung, die den zu ladenden Anbieter identifiziert. Dies ist der registrierte Alias des anbieters für kryptografische Grundtypen. Dieser Parameter ist optional und kann NULL sein, wenn er nicht benötigt wird. Wenn dieser Parameter NULL ist, wird der Standardanbieter für den angegebenen Algorithmus geladen.

Hinweis Wenn der PszImplementation-ParameterwertNULL ist, versucht CNG, jeden registrierten Anbieter in der Reihenfolge der Priorität für den durch den pszAlgId-Parameter angegebenen Algorithmus zu öffnen, und gibt das Handle des ersten Anbieters zurück, der erfolgreich geöffnet wurde. Für die Lebensdauer des Handles verwenden alle kryptografischen BCrypt***-APIs den Anbieter, der erfolgreich geöffnet wurde.

 

Windows Server 2008 und Windows Vista: CNG versucht, auf den Microsoft CNG-Anbieter zurückzugreifen.

Im Folgenden sind die vordefinierten Anbieternamen aufgeführt.

Wert	Bedeutung
MS_PRIMITIVE_PROVIDER "Microsoft Primitive Provider"	Gibt den grundlegenden Microsoft CNG-Anbieter an.
MS_PLATFORM_CRYPTO_PROVIDER L"Microsoft Platform Crypto Provider"	Gibt den TPM-Schlüsselspeicheranbieter an, der von Microsoft bereitgestellt wird.

[in] dwFlags

Flags, die das Verhalten der Funktion ändern. Dies kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.

Wert	Bedeutung
BCRYPT_ALG_HANDLE_HMAC_FLAG	Der Anbieter führt den HMAC-Algorithmus (Hash-Based Message Authentication Code ) mit dem angegebenen Hashalgorithmus aus. Dieses Flag wird nur von Hashalgorithmusanbietern verwendet.
BCRYPT_PROV_DISPATCH	Lädt den Anbieter in den nicht auslagerten Arbeitsspeicherpool. Wenn dieses Flag nicht vorhanden ist, wird der Anbieter in den ausgelagerten Speicherpool geladen. Wenn dieses Flag angegeben wird, darf das zurückgegebene Handle nicht geschlossen werden, bevor alle abhängigen Objekte freigegeben wurden. Hinweis Dieses Flag wird nur im Kernelmodus unterstützt und ermöglicht die Verarbeitung nachfolgender Vorgänge auf dem Anbieter auf Dispatchebene. Wenn der Anbieter den Aufruf auf Verteilerebene nicht unterstützt, gibt er beim Öffnen mit diesem Flag einen Fehler zurück.   Windows Server 2008 und Windows Vista: Dieses Flag wird nur von den Microsoft-Algorithmusanbietern und nur für Hashingalgorithmen und kryptografische Algorithmen für symmetrische Schlüssel unterstützt.
BCRYPT_HASH_REUSABLE_FLAG	Erstellt ein wiederverwendbares Hashingobjekt. Das -Objekt kann unmittelbar nach dem Aufruf von BCryptFinishHash für einen neuen Hashvorgang verwendet werden. Weitere Informationen finden Sie unter Erstellen eines Hashs mit CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Dieses Flag wird nicht unterstützt.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Funktion war erfolgreich.
STATUS_NOT_FOUND	Für die angegebene Algorithmus-ID wurde kein Anbieter gefunden.
STATUS_INVALID_PARAMETER	Mindestens ein Parameter ist ungültig.
STATUS_NO_MEMORY	Ein Speicherbelegungsfehler ist aufgetreten.

Hinweise

Aufgrund der Anzahl und des Typs von Vorgängen, die zum Suchen, Laden und Initialisieren eines Algorithmusanbieters erforderlich sind, ist die Funktion BCryptOpenAlgorithmProvider eine relativ zeitintensive Funktion. Daher wird empfohlen, dass Sie alle Algorithmusanbieterhandles zwischenspeichern, die Sie mehr als einmal verwenden, anstatt die Algorithmusanbieter immer wieder zu öffnen und zu schließen.

BCryptOpenAlgorithmProvider kann entweder aus dem Benutzermodus oder dem Kernelmodus aufgerufen werden. Aufrufer im Kernelmodus müssen in PASSIVE_LEVELIRQL ausgeführt werden.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, die Teil des Driver Development Kit (DDK) ist. Windows Server 2008 und Windows Vista: Verwenden Sie Ksecdd.lib, um diese Funktion im Kernelmodus aufzurufen.

Ab Windows 10 folgt CNG nicht mehr jedem Update der Kryptografiekonfiguration. Bestimmte Änderungen, z. B. das Hinzufügen eines neuen Standardanbieters oder das Ändern der Einstellungsreihenfolge von Algorithmusanbietern, erfordern möglicherweise einen Neustart. Aus diesem Fall sollten Sie einen Neustart durchführen, bevor Sie BCryptOpenAlgorithmProvider mit einem neu konfigurierten Anbieter aufrufen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	bcrypt.h
Bibliothek	Bcrypt.lib
DLL	Bcrypt.dll

Weitere Informationen

BCryptCloseAlgorithmProvider