BCryptDeriveKey-Funktion (bcrypt.h)

Die Funktion "BCryptDeriveKey " leitet einen Schlüssel von einem BCRYPT_SECRET_HANDLE ab. Dies erfolgt in der Regel im Rahmen eines Geheimvertragsverfahrens.

Die Schlüsselableitung von einem geheimen Schlüssel, der direkt vom Aufrufer bereitgestellt wird, finden Sie unter "BCryptKeyDerivation".

Syntax

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

Parameter

[in] hSharedSecret

Der geheime Handle zum Erstellen des Schlüssels aus. Dieses Handle wird von der Funktion BCryptSecretAgreement abgerufen.

[in] pwszKDF

Ein Zeiger auf eine mit Null beendete Unicode-Zeichenfolge, die die Schlüsselableitungsfunktion (Key Ableitungsfunktion , KDF) identifiziert, die zum Ableiten des Schlüssels verwendet werden soll. Dies kann eine der folgenden Zeichenfolgen sein.

BCRYPT_KDF_HASH (L"HASH")

Verwenden Sie die Hashtastenableitungsfunktion.

Wenn der cbDerivedKey-Parameter kleiner als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion nur die angegebene Anzahl von Bytes in den PbDerivedKey-Puffer . Dies ist in der Regel schlecht, da sie die Sicherheitsstärke des resultierenden Schlüssels erheblich reduzieren kann.

Wenn der cbDerivedKey-Parameter größer als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion den Schlüssel in den PbDerivedKey-Puffer und legt die Variable fest, auf die das pcbResult verweist, auf die tatsächliche Anzahl der kopierten Bytes.

Die parameter, die vom pParameterList-Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie durch die Erforderliche oder optionale Spalte angegeben.

Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")

Verwenden Sie die Schlüsselableitungsfunktion Hash-Based Nachrichtenauthentifizierungscode (HMAC).

Wenn der cbDerivedKey-Parameter kleiner als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion nur die angegebene Anzahl von Bytes in den PbDerivedKey-Puffer . Dies ist in der Regel schlecht, da sie die Sicherheitsstärke des resultierenden Schlüssels erheblich reduzieren kann.

Wenn der cbDerivedKey-Parameter größer als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion den Schlüssel in den PbDerivedKey-Puffer und legt die Variable fest, auf die das pcbResult verweist, auf die tatsächliche Anzahl der kopierten Bytes.

Die parameter, die vom pParameterList-Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie durch die Erforderliche oder optionale Spalte angegeben.

Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

Verwenden Sie die Tls-Schlüsselableitungsfunktion ( Transport Layer Security , Pseudo-Random Function , PRF). Die Größe des abgeleiteten Schlüssels beträgt immer 48 Bytes, sodass der cbDerivedKey-Parameter 48 sein muss.

Die parameter, die vom pParameterList-Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie durch die Erforderliche oder optionale Spalte angegeben.

Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

Verwenden Sie die SP800-56A-Schlüsselableitungsfunktion. Dies wird auch als "SP800-56C rev2 one-step KDF" bezeichnet.

Die KDF akzeptiert eine genehmigte Hashfunktion als Parameter, aber diese API wählt die Hashfunktion intern aus und stimmt mit der Sicherheitsstärke des Hashalgorithmus mit dem Algorithmus überein, der zum Generieren des geheimen Handles verwendet wird. (d. h. ECDH P-256 verwendet SHA256, ECDH P-384 verwendet SHA384)

Die parameter, die vom pParameterList-Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie durch die Erforderliche oder optionale Spalte angegeben. Alle Parameterwerte werden als undurchsichtige Bytearrays behandelt.

Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.

KDF-Output = SP_800-56A_KDF(
    hSharedSecret,
    KDF_ALGORITHMID,
    KDF_PARTYUINFO,
    KDF_PARTYVINFO,
    KDF_SUPPPUBINFO,
    KDF_SUPPPRIVINFO)

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Gibt die Little-Endian-Darstellung des rohen Geheimschlüssels ohne Änderung zurück. Die Verwendung dieser Option ist in der Regel nicht empfehlenswert, kann jedoch erforderlich sein, wenn Sie mit einer nicht unterstützten KDF zusammenarbeiten müssen.

Wenn der cbDerivedKey-Parameter kleiner als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion nur die angegebene Anzahl von Bytes in den PbDerivedKey-Puffer . Dies ist in der Regel schlecht, da sie die Sicherheitsstärke des resultierenden Schlüssels erheblich reduzieren kann.

Wenn der cbDerivedKey-Parameter größer als die Größe des abgeleiteten Schlüssels ist, kopiert diese Funktion den Schlüssel in den PbDerivedKey-Puffer und legt die Variable fest, auf die das pcbResult verweist, auf die tatsächliche Anzahl der kopierten Bytes.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

BCRYPT_KDF_HKDF (L"HKDF")

Verwenden Sie die HKDF-Funktion (HMAC-based Extract-and-Expand KDF) aus RFC 5869.

In HKDF wird zwischen der Ableitung eines Schlüssels von einem der folgenden Methoden unterschieden:

1. Die Ausgabe einer geheimen Vereinbarungsfunktion, die nicht einheitlich zufällig ist und als Eingabetastenmaterial (IKM) gilt. Fast alle Benutzer von BCryptDeriveKey verfügen über einen geheimen Handle dieses Formulars.
2. Ein einheitlich zufälliger geheimer Wert.

Der erste Schritt besteht darin, einen Pseudorandomschlüssel (PRK) aus dem geheimen Handle zu extrahieren.

Dieser Schritt wird ausgeführt, indem BCryptSetProperty für ein geheimes Handle mit BCRYPT_HKDF_HASH_ALGORITHM aufgerufen wird, um den Hashalgorithmus festzulegen, der in HMAC-Berechnungen in HKDF verwendet werden soll. Dies folgt ein zweiter Aufruf von BCryptSetProperty mit einer der folgenden:

1. Wenn der geheime Handle IKM darstellt, verwenden Sie BCRYPT_HKDF_SALT_AND_FINALIZE , um den optionalen Salzwert bereitzustellen und die PRK aus dem IKM zu extrahieren und den geheimen Handle abzuschließen.
2. Verwenden Sie andernfalls BCRYPT_HKDF_PRK_AND_FINALIZE , um den geheimen Wert direkt in den HKDF PRK zu transformieren und den geheimen Handle abzuschließen.

Der zweite Schritt besteht darin, die PRK in einen abgeleiteten Ausgabeschlüssel zu erweitern.

Dieser Schritt wird durch Aufrufen von BCryptDeriveKey für ein abgeschlossenes geheimes Handle ausgeführt.

Die parameter, die vom pParameterList-Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie durch die Erforderliche oder optionale Spalte angegeben. Alle Parameterwerte werden als undurchsichtige Bytearrays behandelt.

Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10: Die Unterstützung für HKDF beginnt.

[in, optional] pParameterList

Die Adresse einer BCryptBufferDesc-Struktur , die die KDF-Parameter enthält. Dieser Parameter ist optional und kann sein NULL , wenn er nicht benötigt wird.

[out, optional] pbDerivedKey

Die Adresse eines Puffers, der den Schlüssel empfängt. Der parameter cbDerivedKey enthält die Größe dieses Puffers. Wenn dieser Parameter lautet NULL, platziert diese Funktion die erforderliche Größe in Bytes in der ULONG , auf die der pcbResult-Parameter verweist.

[in] cbDerivedKey

Die Größe des PbDerivedKey-Puffers in Bytes.

[out] pcbResult

Ein Zeiger auf eine ULONG , die die Anzahl der Bytes empfängt, die in den PbDerivedKey-Puffer kopiert wurden. Wenn der PbDerivedKey-Parameter lautet NULL, platziert diese Funktion die erforderliche Größe in Bytes in der ULONG , auf die dieser Parameter verweist.

[in] dwFlags

Eine Reihe von Flags, die das Verhalten dieser Funktion ändern.

Dies kann null oder der folgende Wert sein:

Rückgabewert

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

Mögliche Rückgabecodes umfassen, sind jedoch nicht beschränkt auf Folgendes:

Bemerkungen

Die BCryptBufferDesc-Struktur im pParameterList-Parameter kann mehr als einen der KDF_SECRET_PREPEND und KDF_SECRET_APPEND Parameter enthalten. Wenn mehrere dieser Parameter angegeben werden, werden die Parameterwerte in der Reihenfolge verkettet, in der sie im Array enthalten sind, bevor die KDF aufgerufen wird. Angenommen, die folgenden Parameterwerte werden angegeben.

BYTE abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

Wenn die obigen Parameterwerte angegeben werden, sind die verketteten Werte für die tatsächliche KDF wie folgt.

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

Wenn der pwszKDF-Parameter auf BCRYPT_KDF_RAW_SECRET festgelegt ist, wird der zurückgegebene geheime Schlüssel (im Gegensatz zu den anderen pwszKDF-Werten ) im Little-End-Format codiert. Es ist wichtig, dies zu beachten, wenn sie das rohe Geheimnis in allen anderen CNG-Funktionen verwenden, da die meisten von ihnen big-endian-codierte Eingaben übernehmen.

Bei Verwendung eines unterstützten Algorithmusanbieters kann BCryptDeriveKey entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder bei PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss sich das im hSharedSecret-Parameter bereitgestellte Handle im nicht seitenfreien (oder gesperrten) Speicher befinden und von einem Algorithmushandle abgeleitet werden, das von einem Anbieter zurückgegeben wird, der mithilfe des BCRYPT_PROV_DISPATCH Flags geöffnet wurde.

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

Anforderungen

Siehe auch

BCryptBufferDesc

BCryptSecretAgreement