NCryptDeriveKey-Funktion (ncrypt.h)
Die NCryptDeriveKey-Funktion leitet einen Schlüssel von einem Geheimvertragswert ab. Diese Funktion ist für die Verwendung als Teil einer Geheimvereinbarungsprozedur unter Verwendung persistenter geheimer Vereinbarungsschlüssel vorgesehen. Verwenden Sie stattdessen die Funktion NCryptKeyDerivation , um Schlüsselmaterial mithilfe eines persistenten Geheimnisses abzuleiten.
Syntax
SECURITY_STATUS NCryptDeriveKey(
[in] NCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] NCryptBufferDesc *pParameterList,
[out, optional] PBYTE pbDerivedKey,
[in] DWORD cbDerivedKey,
[out] DWORD *pcbResult,
[in] ULONG dwFlags
);
Parameter
[in] hSharedSecret
Das Geheimvertragshandle, aus dem der Schlüssel erstellt werden soll. Dieses Handle wird von der Funktion NCryptSecretAgreement abgerufen.
[in] pwszKDF
Ein Zeiger auf eine Unicode-Zeichenfolge mit Null-Beendigung, die die Schlüsselableitungsfunktion (Key Derivation 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 Puffer pbDerivedKey und legt die Variable, auf die vom pcbResult verwiesen wird, 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-Beendigung, die den zu verwendenden Hashalgorithmus identifiziert. Dies kann einer der Standardhashalgorithmusbezeichner von CNG-Algorithmusbezeichnern oder der Bezeichner für einen anderen registrierten Hashalgorithmus sein.
Wenn dieser Parameter nicht angegeben wird, wird der SHA1-Hashalgorithmus verwendet. |
Optional |
| KDF_SECRET_PREPEND | Ein Wert, der der Hashfunktion am Anfang der Nachrichteneingabe hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
| KDF_SECRET_APPEND | Ein Wert, der der Hashfunktion am Ende der Nachrichteneingabe hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
Der Aufruf des 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 Puffer pbDerivedKey und legt die Variable, auf die vom pcbResult verwiesen wird, 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-Beendigung, die den zu verwendenden Hashalgorithmus identifiziert. Dies kann einer der Standardhashalgorithmusbezeichner von CNG-Algorithmusbezeichnern oder der Bezeichner für einen anderen registrierten Hashalgorithmus sein.
Wenn dieser Parameter nicht angegeben wird, 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 der Hashfunktion am Anfang der Nachrichteneingabe hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
| KDF_SECRET_APPEND | Ein Wert, der der Hashfunktion am Ende der Nachrichteneingabe hinzugefügt werden soll. Weitere Informationen finden Sie in den Hinweisen. | Optional |
Der Aufruf des 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 Bytes lang sein. | Erforderlich |
Der Aufruf des 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. Sie enthält private Informationen, die sowohl dem Initiator als auch dem Responder bekannt sind, z. B. ein gemeinsam genutztes Geheimnis. | Optional |
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.
[in, optional] pParameterList
Die Adresse einer NCryptBufferDesc-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 Byte im DWORD , auf das der pcbResult-Parameter verweist.
[in] cbDerivedKey
Die Größe des pbDerivedKey-Puffers in Bytes.
[out] pcbResult
Ein Zeiger auf ein DWORD , das die Anzahl der Bytes empfängt, die in den pbDerivedKey-Puffer kopiert wurden. Wenn der pbDerivedKey-ParameterNULL ist, platziert diese Funktion die erforderliche Größe in Byte im DWORD , auf das dieser Parameter verweist.
[in] dwFlags
Ein Satz 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 sind u. a. die folgenden:
| Rückgabecode | Beschreibung |
|---|---|
|
Die Funktion war erfolgreich. |
|
Der hSharedSecret-Parameter ist ungültig. |
|
Mindestens ein Parameter ist ungültig. |
Hinweise
Die BCryptBufferDesc-Struktur im pParameterList-Parameter kann mehr als einen der parameter KDF_SECRET_PREPEND und KDF_SECRET_APPEND 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 sind, lauten die verketteten Werte mit der 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
Ein Dienst darf diese Funktion nicht über seine StartService-Funktion aufrufen. Wenn ein Dienst diese Funktion über seine StartService-Funktion aufruft, kann ein Deadlock auftreten, und der Dienst reagiert möglicherweise nicht mehr.
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 | ncrypt.h |
| Bibliothek | Ncrypt.lib |
| DLL | Ncrypt.dll |