NCryptKeyDerivation-Funktion (ncrypt.h)

  • Artikel

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