NCryptKeyDerivation-Funktion (ncrypt.h)

Artikel
03/06/2024

Die Funktion NCryptKeyDerivation erstellt mithilfe der angegebenen Schlüsselableitungsfunktion einen Schlüssel aus einem anderen Schlüssel. Die Funktion gibt den Schlüssel in einem Bytearray zurück.

Syntax

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Parameter

[in] hKey

Handle des KDF-Schlüssels (Key Derivation Function).

[in] pParameterList

Die Adresse einer NCryptBufferDesc-Struktur , die die KDF-Parameter enthält. Die Parameter können spezifisch für ein KDF-Format oder generisch sein. In der folgenden Tabelle sind die erforderlichen und optionalen Parameter für bestimmte KDFs aufgeführt, die vom Microsoft-Softwareschlüsselspeicheranbieter implementiert werden.

KDF	Parameter	Erforderlich
SP800-108 HMAC im Zählermodus	KDF_LABEL	ja
	KDF_CONTEXT	ja
	KDF_HASH_ALGORITHM	ja
SP800-56A	KDF_ALGORITHMID	ja
	KDF_PARTYUINFO	ja
	KDF_PARTYVINFO	ja
	KDF_HASH_ALGORITHM	ja
	KDF_SUPPPUBINFO	nein
	KDF_SUPPPRIVINFO	nein
PBKDF2	KDF_HASH_ALGORITHM	ja
	KDF_SALT	ja
	KDF_ITERATION_COUNT	nein
CAPI_KDF	KDF_HASH_ALGORITHM	ja

Der folgende generische Parameter kann verwendet werden:

KDF_GENERIC_PARAMETER

Generische Parameter werden KDF-spezifischen Parametern wie folgt zugeordnet:

SP800-108 HMAC im Zählermodus:

KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

KDF_GENERIC_PARAMETER = KDF_SALT
KDF_ITERATION_COUNT – Standardwert 10000

CAPI_KDF

KDF_GENERIC_PARAMETER = Nicht verwendet

[out] pbDerivedKey

Adresse eines Puffers, der den Schlüssel empfängt. Der cbDerivedKey-Parameter enthält die Größe des Schlüsselpuffers in Bytes.

[in] cbDerivedKey

Größe des Puffers in Bytes, auf den der PbDerivedKey-Parameter verweist.

[out] pcbResult

Zeiger auf ein DWORD , das die Anzahl der Bytes empfängt, die in den Puffer kopiert werden, auf den der pbDerivedKey-Parameter verweist.

[in] dwFlags

Flags, die das Funktionsverhalten ändern. Der folgende Wert kann mit dem Microsoft-Softwareschlüsselspeicheranbieter verwendet werden.

Wert	Bedeutung
BCRYPT_CAPI_AES_FLAG	Gibt an, dass der Zielalgorithmus AES ist und dass der Schlüssel daher doppelt erweitert werden muss. Dieses Flag ist nur für den CAPI_KDF-Algorithmus gültig.
NCRYPT_SILENT_FLAG	Fordert an, dass der Schlüsseldienstanbieter (Key Service Provider, KSP) keine Benutzeroberfläche anzeigt. Wenn der Anbieter die Benutzeroberfläche anzeigen muss, um zu funktionieren, schlägt der Aufruf fehl, und der KSP sollte den NTE_SILENT_CONTEXT Fehlercode als letzten Fehler festlegen.

Rückgabewert

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

Mögliche Rückgabecodes umfassen folgendes, sind aber nicht darauf beschränkt.

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_INVALID_HANDLE	Die hProvider - oder hKey-Handles sind ungültig.
NTE_INVALID_PARAMETER	Die Parameter pwszDerivedKeyAlg und pParameterList können nicht NULL sein.
NTE_NO_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um den Schlüssel zu erstellen.
NTE_NOT_SUPPORTED	Diese Funktion wird vom Schlüsselspeicheranbieter nicht unterstützt.

Hinweise

Sie können die folgenden Algorithmusbezeichner in der Funktion NCryptCreatePersistedKey verwenden, bevor Sie NCryptKeyDerivation aufrufen:

BCRYPT_CAPI_KDF_ALGORITHM
BCRYPT_SP800108_CTR_HMAC_ALGORITHM
BCRYPT_SP80056A_CONCAT_ALGORITHM
BCRYPT_PBKDF2_ALGORITHM

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	ncrypt.h
Bibliothek	Ncrypt.lib
DLL	Ncrypt.dll

Weitere Informationen

BCryptKeyDerivation

NCryptDeriveKey

Freigeben über