BCryptDeriveKey-Funktion (bcrypt.h)
Die BCryptDeriveKey Funktion leitet einen Schlüssel von einem geheimen Vertragswert ab.
Die Schlüsselableitung von einem bestimmten Geheimnis 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 Vereinbarungshandle zum Erstellen des Schlüssels aus. Dieses Handle wird aus der BCryptSecretAgreement-Funktion abgerufen.
[in] pwszKDF
Ein Zeiger auf eine mit Null beendete Unicode-Zeichenfolge, die die Schlüsselableitungsfunktion (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. 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 vom pcbResult auf die tatsächliche Anzahl kopierter Bytes verweist.
Die parameter, die vom pParameterList Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie in der Spalte "Erforderlich" oder "Optional" angegeben.
| Parameter | Beschreibung | Erforderlich oder optional |
|---|---|---|
| KDF_HASH_ALGORITHM |
Eine mit Null beendete Unicode-Zeichenfolge, die den zu verwendenden Hashalgorithmus identifiziert. Hierbei kann es sich um einen der standardmäßigen Hashalgorithmus-IDs aus CNG-Algorithmusbezeichnern oder um den Bezeichner für einen anderen registrierten Hashalgorithmus handeln.
Wenn dieser Parameter nicht angegeben ist, wird der SHA1-Hashalgorithmus verwendet. |
Wahlfrei |
| KDF_SECRET_PREPEND | Ein Wert, der am Anfang der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Wahlfrei |
| KDF_SECRET_APPEND | Ein Wert, der am Ende der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Wahlfrei |
Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
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. 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 vom pcbResult auf die tatsächliche Anzahl kopierter Bytes verweist.
Die parameter, die vom pParameterList Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie in der Spalte "Erforderlich" oder "Optional" angegeben.
| Parameter | Beschreibung | Erforderlich oder optional |
|---|---|---|
| KDF_HASH_ALGORITHM |
Eine mit Null beendete Unicode-Zeichenfolge, die den zu verwendenden Hashalgorithmus identifiziert. Hierbei kann es sich um einen der standardmäßigen Hashalgorithmus-IDs aus CNG-Algorithmusbezeichnern oder um den Bezeichner für einen anderen registrierten Hashalgorithmus handeln.
Wenn dieser Parameter nicht angegeben ist, wird der SHA1-Hashalgorithmus verwendet. |
Wahlfrei |
| KDF_HMAC_KEY | Der Schlüssel, der für die Pseudo-Zufallsfunktion (PRF) verwendet werden soll. | Wahlfrei |
| KDF_SECRET_PREPEND | Ein Wert, der am Anfang der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Wahlfrei |
| KDF_SECRET_APPEND | Ein Wert, der am Ende der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Wahlfrei |
Der Aufruf der KDF erfolgt wie im folgenden Pseudocode dargestellt.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
KDF-Output = HMAC-Hash(
KDF_HMAC_KEY,
KDF-Prepend +
hSharedSecret +
KDF-Append)
BCRYPT_KDF_TLS_PRF (L"TLS_PRF")
Verwenden Sie die Transport layer security (TLS) pseudo-random function (PRF)-Schlüsselableitungsfunktion. Die Größe des abgeleiteten Schlüssels beträgt immer 48 Byte, 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 in der Spalte "Erforderlich" oder "Optional" angegeben.
| Parameter | Beschreibung | Erforderlich oder optional |
|---|---|---|
| KDF_TLS_PRF_LABEL | Eine ANSI-Zeichenfolge, die die PRF-Bezeichnung enthält. | Erforderlich |
| KDF_TLS_PRF_SEED | Der PRF-Samen. Der Seed muss 64 Byte lang sein. | Erforderlich |
| KDF_TLS_PRF_PROTOCOL |
Ein DWORD- Wert, der die TLS-Protokollversion angibt, deren PRF-Algorithmus verwendet werden soll.
Gültige Werte sind:
Windows Server 2008 und Windows Vista: TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION und DTLS1_0_PROTOCOL_VERSION werden nicht unterstützt. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: DTLS1_0_PROTOCOL_VERSION wird nicht unterstützt. |
Wahlfrei |
| KDF_HASH_ALGORITHM | Die CNG-Algorithmus-ID des Hashs, der mit dem HMAC in der PRF verwendet werden soll, für die TLS 1.2-Protokollversion. Gültige Auswahlmöglichkeiten sind SHA-256 und SHA-384. Wenn nicht angegeben, wird SHA-256 verwendet. | Wahlfrei |
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.
Die parameter, die vom pParameterList Parameter identifiziert werden, können oder müssen die folgenden Parameter enthalten, wie in der Spalte "Erforderlich" oder "Optional" angegeben. Alle Parameterwerte werden als undurchsichtige Bytearrays behandelt.
| Parameter | Beschreibung | Erforderlich oder optional |
|---|---|---|
| KDF_ALGORITHMID | Gibt das AlgorithmID- Unterfeld des Felds OtherInfo in der Sp800-56A-Schlüsselableitungsfunktion an. Gibt den beabsichtigten Zweck des abgeleiteten Schlüssels an. | Erforderlich |
| KDF_PARTYUINFO | Gibt das PartyUInfo Unterfeld des Felds OtherInfo in der FUNKTION SP800-56A-Schlüsselableitung an. Das Feld enthält öffentliche Informationen, die vom Initiator beigetragen wurden. | Erforderlich |
| KDF_PARTYVINFO | Gibt das PartyVInfo Unterfeld des Felds OtherInfo in der Sp800-56A-Schlüsselableitungsfunktion an. Das Feld enthält öffentliche Informationen, die vom Antwortenden beigetragen wurden. | Erforderlich |
| KDF_SUPPPUBINFO | Gibt das SuppPubInfo- Unterfeld des Felds OtherInfo in der Sp800-56A-Schlüsselableitungsfunktion an. Das Feld enthält öffentliche Informationen, die sowohl initiator als auch responder bekannt sind. | Wahlfrei |
| KDF_SUPPPRIVINFO | Gibt das SuppPrivInfo- Unterfeld des Felds OtherInfo in der FUNKTION SP800-56A-Schlüsselableitung an. Sie enthält private Informationen, die sowohl initiator als auch responder bekannt sind, z. B. einen freigegebenen geheimen Schlüssel. | Wahlfrei |
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.
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. 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 vom pcbResult auf die tatsächliche Anzahl kopierter Bytes verweist.
Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
[in, optional] pParameterList
Die Adresse einer BCryptBufferDesc- Struktur, die die KDF-Parameter enthält. Dieser Parameter ist optional und kann NULL- werden, 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 NULL-ist, platziert diese Funktion die erforderliche Größe in Byte in den ULONG-, auf die der pcbResult-Parameter verweist.
[in] cbDerivedKey
Die Größe des pbDerivedKey- Puffers in Byte.
[out] pcbResult
Ein Zeiger auf eine ULONG-, die die Anzahl der Bytes empfängt, die in den PbDerivedKey- Puffer kopiert wurden. Wenn der parameter pbDerivedKeyNULList, platziert diese Funktion die erforderliche Größe in Byte 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, aber nicht beschränkt auf Folgendes.
| Rückgabecode | Beschreibung |
|---|---|
|
Die Funktion war erfolgreich. |
|
Interner Fehler. |
|
Das Handle im hSharedSecret--Parameter ist ungültig. |
|
Mindestens ein Parameter ist ungültig. |
Bemerkungen
Die BCryptBufferDesc- Struktur im pParameterList Parameter kann mehr als einen der parameter KDF_SECRET_PREPEND und KDF_SECRET_APPEND 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 pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};
Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);
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 parameter pwszKDF auf BCRYPT_KDF_RAW_SECRETfestgelegt ist, wird das zurückgegebene Geheimnis (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.
Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptDeriveKey entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL- oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEList, muss sich das im hSharedSecret Parameter bereitgestellte Handle im nichtpageten (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.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.
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 |