BCryptOpenAlgorithmProvider Funktion (bcrypt.h)

Artikel
07/16/2024

Die BCryptOpenAlgorithmProvider Funktion 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 CNG-Anbieterhandle empfängt. Wenn Sie diesen Handle verwendet haben, lassen Sie es los, indem Sie es an die BCryptCloseAlgorithmProvider-Funktion übergeben.

[in] pszAlgId

Ein Zeiger auf eine mit Null beendete Unicode-Zeichenfolge, 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 mit Null beendete Unicode-Zeichenfolge, die den zu ladenden anbieter identifiziert. Dies ist der registrierte Alias des kryptografischen Grundtypanbieters. Dieser Parameter ist optional und kann NULL- werden, wenn er nicht benötigt wird. Wenn dieser Parameter NULL-ist, wird der Standardanbieter für den angegebenen Algorithmus geladen.

Hinweis Wenn der pszImplementation Parameterwert NULList, versucht CNG, jeden registrierten Anbieter in Reihenfolge der Priorität zu öffnen, für den algorithmus, der durch den pszAlgId Parameter angegeben wurde, 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"	Identifiziert den grundlegenden Microsoft CNG-Anbieter.
MS_PLATFORM_CRYPTO_PROVIDER L"Microsoft Platform Crypto Provider"	Identifiziert den TPM-Schlüsselspeicheranbieter, 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 algorithmus Hash-Based Nachrichtenauthentifizierungscode (HMAC) mit dem angegebenen Hashalgorithmus aus. Dieses Flag wird nur von Hashalgorithmusanbietern verwendet.
BCRYPT_PROV_DISPATCH	Lädt den Anbieter in den Nichtseitenspeicherpool. Wenn dieses Flag nicht vorhanden ist, wird der Anbieter in den ausgelagerten Speicherpool geladen. Wenn dieses Kennzeichen angegeben ist, darf das zurückgegebene Handle nicht geschlossen werden, bevor alle abhängigen Objekte freigegeben wurden. Hinweis Dieses Kennzeichen wird nur im Kernelmodus unterstützt und ermöglicht nachfolgenden Vorgängen des Anbieters die Verarbeitung auf Dispatch-Ebene. Wenn der Anbieter das Aufrufen auf Verteilerebene nicht unterstützt, wird beim Öffnen dieses Flags ein Fehler zurückgegeben. Windows Server 2008 und Windows Vista: Dieses Flag wird nur von den Microsoft-Algorithmusanbietern unterstützt und nur für Hashingalgorithmen und symmetrischen Schlüssel kryptografischen Algorithmen.
BCRYPT_HASH_REUSABLE_FLAG	Erstellt ein wiederverwendbares Hashing-Objekt. Das Objekt kann sofort nach dem Aufrufen BCryptFinishHashfür einen neuen Hashingvorgang verwendet werden. Weitere Informationen finden Sie unter Creating a Hash with CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Dieses Flag wird nicht unterstützt.

Rückgabewert

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

Mögliche Rückgabecodes umfassen, aber nicht beschränkt auf Folgendes.

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	Fehler bei der Speicherzuweisung.

Bemerkungen

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

BCryptOpenAlgorithmProvider kann entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodus-Aufrufer müssen bei PASSIVE_LEVELIRQL-ausgeführt werden.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, das 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 Gründen sollten Sie einen Neustart durchführen, bevor Sie BCryptOpenAlgorithmProvider mit jedem neu konfigurierten Anbieter aufrufen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	bcrypt.h
Library	Bcrypt.lib
DLL-	Bcrypt.dll

Siehe auch

BCryptCloseAlgorithmProvider

Freigeben über