BCryptDeriveKey-Funktion (bcrypt.h)
Die Funktion BCryptDeriveKey leitet einen Schlüssel von einem Geheimvertragswert ab.
Informationen zur 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
Das Geheimvertragshandle, aus dem der Schlüssel erstellt werden soll. Dieses Handle wird von der Funktion BCryptSecretAgreement abgerufen.
[in] pwszKDF
Ein Zeiger auf eine mit NULL endende Unicode-Zeichenfolge, die die Schlüsselableitungsfunktion (Key Deivation Function , 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 Hashschlüsselableitungsfunktion.
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, auf die das pcbResult zeigt, auf die tatsächliche Anzahl der kopierten Bytes fest.
Die durch den pParameterList-Parameter identifizierten Parameter 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 Unicode-Zeichenfolge mit Null-Termin, die den zu verwendenden Hashalgorithmus identifiziert. Dies kann einer der Standard-Hashalgorithmusbezeichner von CNG-Algorithmusbezeichnern oder der Bezeichner für einen anderen registrierten Hashalgorithmus sein.
Wenn dieser Parameter nicht angegeben ist, wird der SHA1-Hashalgorithmus verwendet. |
Optional |
| KDF_SECRET_PREPEND | Ein Wert, der am Anfang der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
| KDF_SECRET_APPEND | Ein Wert, der am Ende der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
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 HMAC-Schlüsselableitungsfunktion ( Hash-Based Message Authentication Code ).
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, auf die das pcbResult zeigt, auf die tatsächliche Anzahl der kopierten Bytes fest.
Die durch den pParameterList-Parameter identifizierten Parameter 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 Unicode-Zeichenfolge mit Null-Termin, die den zu verwendenden Hashalgorithmus identifiziert. Dies kann einer der Standard-Hashalgorithmusbezeichner von CNG-Algorithmusbezeichnern oder der Bezeichner für einen anderen registrierten Hashalgorithmus sein.
Wenn dieser Parameter nicht angegeben ist, wird der SHA1-Hashalgorithmus verwendet. |
Optional |
| KDF_HMAC_KEY | Der Schlüssel, der für die Pseudo-Zufallsfunktion (PRF ) verwendet werden soll. | Optional |
| KDF_SECRET_PREPEND | Ein Wert, der am Anfang der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
| KDF_SECRET_APPEND | Ein Wert, der am Ende der Nachrichteneingabe zur Hashfunktion hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
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 Schlüsselableitungsfunktion der Pseudo-Zufallsfunktion (Transport Layer Security, TLS). Die Größe des abgeleiteten Schlüssels beträgt immer 48 Bytes, sodass der cbDerivedKey-Parameter 48 sein muss.
Die durch den pParameterList-Parameter identifizierten Parameter 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-Seed. 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 werden TLS1_2_PROTOCOL_VERSION und DTLS1_0_PROTOCOL_VERSION nicht unterstützt. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: DTLS1_0_PROTOCOL_VERSION wird nicht unterstützt. |
Optional |
| KDF_HASH_ALGORITHM | Die CNG-Algorithmus-ID des Hashs, der mit dem HMAC in der PRF für die TLS 1.2-Protokollversion verwendet werden soll. Gültige Optionen sind SHA-256 und SHA-384. Wenn nicht angegeben, wird SHA-256 verwendet. | Optional |
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 Schlüsselableitungsfunktion SP800-56A.
Die durch den pParameterList-Parameter identifizierten Parameter 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 Unterfeld AlgorithmID des Felds OtherInfo in der Schlüsselableitungsfunktion SP800-56A an. Gibt den beabsichtigten Zweck des abgeleiteten Schlüssels an. | Erforderlich |
| KDF_PARTYUINFO | Gibt das Unterfeld PartyUInfo des Felds OtherInfo in der Schlüsselableitungsfunktion SP800-56A an. Das Feld enthält öffentliche Informationen, die vom Initiator bereitgestellt werden. | Erforderlich |
| KDF_PARTYVINFO | Gibt das Unterfeld PartyVInfo des Felds OtherInfo in der Schlüsselableitungsfunktion SP800-56A an. Das Feld enthält öffentliche Informationen, die vom Responder bereitgestellt werden. | Erforderlich |
| KDF_SUPPPUBINFO | Gibt das Unterfeld SuppPubInfo des Felds OtherInfo in der Schlüsselableitungsfunktion SP800-56A an. Das Feld enthält öffentliche Informationen, die sowohl dem Initiator als auch dem Antwortgeber bekannt sind. | Optional |
| KDF_SUPPPRIVINFO | Gibt das Unterfeld SuppPrivInfo des Felds OtherInfo in der Schlüsselableitungsfunktion SP800-56A an. Es enthält private Informationen, die sowohl dem Initiator als auch dem Antwortgeber bekannt sind, z. B. ein gemeinsam genutztes Geheimnis. | Optional |
Der Aufruf des 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 Geheimnisses ohne Änderungen 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 Puffer pbDerivedKey und legt die Variable, auf die vom pcbResult verwiesen wird, auf die tatsächliche Anzahl der kopierten Bytes fest.
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 sein, wenn er nicht benötigt wird.
[out, optional] pbDerivedKey
Die Adresse eines Puffers, der den Schlüssel empfängt. Der cbDerivedKey-Parameter enthält die Größe dieses Puffers. Wenn dieser Parameter NULL ist, 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 Puffer pbDerivedKey kopiert wurden. Wenn der pbDerivedKey-ParameterNULL ist, 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 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 |
|---|---|
|
Die Funktion war erfolgreich. |
|
Interner Fehler. |
|
Das Handle im hSharedSecret-Parameter ist ungültig. |
|
Mindestens ein Parameter ist ungültig. |
Hinweise
Die BCryptBufferDesc-Struktur im pParameterList-Parameter kann mehr als einen der KDF_SECRET_PREPEND - und KDF_SECRET_APPEND-Parameter enthalten. Wenn mehr als einer dieser Parameter angegeben wird, werden die Parameterwerte in der Reihenfolge verkettet, in der sie im Array enthalten sind, bevor die KDF aufgerufen wird. Angenommen, die folgenden Parameterwerte sind 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, lauten die verketteten Werte mit dem tatsächlichen 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 the returned secret (im Gegensatz zu den anderen pwszKDF-Werten ) im Little-Endian-Format codiert. Es ist wichtig, dies zu beachten, wenn Sie das rohe Geheimnis in anderen CNG-Funktionen verwenden, da die meisten von ihnen big-endian-codierte Eingaben verwenden.
Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptDeriveKey entweder im Benutzermodus oder im Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausführen. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss sich das im hSharedSecret-Parameter bereitgestellte Handle im nicht auslieferten (oder gesperrten) Arbeitsspeicher befinden und von einem Algorithmushandle abgeleitet werden, das von einem Anbieter zurückgegeben wird, der mit dem BCRYPT_PROV_DISPATCH-Flag geöffnet wurde.
Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, die Teil des Driver Development Kit (DDK) ist. Windows Server 2008 und Windows Vista: Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Ksecdd.lib.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | bcrypt.h |
| Bibliothek | Bcrypt.lib |
| DLL | Bcrypt.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für