CryptDeriveKey-Funktion (wincrypt.h)
Diese Funktion ist identisch mit CryptGenKey, mit dem Unterschied, dass die generierten Sitzungsschlüssel aus Basisdaten abgeleitet werden, anstatt zufällig zu sein. CryptDeriveKey kann nur zum Generieren von Sitzungsschlüsseln verwendet werden. Es können keine öffentlichen/privaten Schlüsselpaare generiert werden.
Im parameter phKey wird ein Handle für den Sitzungsschlüssel zurückgegeben. Dieses Handle kann mit jeder CryptoAPI-Funktion verwendet werden, die ein Schlüsselhandle erfordert.
Syntax
BOOL CryptDeriveKey(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] HCRYPTHASH hBaseData,
[in] DWORD dwFlags,
[in, out] HCRYPTKEY *phKey
);
Parameter
[in] hProv
Ein HCRYPTPROV-Handle eines CSP, der durch einen Aufruf von CryptAcquireContext erstellt wurde.
[in] Algid
Eine ALG_ID-Struktur , die den symmetrischen Verschlüsselungsalgorithmus identifiziert, für den der Schlüssel generiert werden soll. Die verfügbaren Algorithmen sind wahrscheinlich für jeden CSP unterschiedlich. Weitere Informationen dazu, welcher Algorithmusbezeichner von den verschiedenen Anbietern für die Schlüsselspezifikationen AT_KEYEXCHANGE und AT_SIGNATURE verwendet wird, finden Sie unter ALG_ID.
Weitere Informationen zu ALG_ID Werten, die mit dem Microsoft Base-Kryptografieanbieter verwendet werden sollen, finden Sie unter Basisanbieteralgorithmen. Weitere Informationen zu ALG_ID Werten, die mit dem Microsoft Strong Cryptographic Provider oder dem Microsoft Enhanced Cryptographic Provider verwendet werden sollen, finden Sie unter Erweiterte Anbieteralgorithmen.
[in] hBaseData
Ein Handle für ein Hashobjekt , dem die genauen Basisdaten zugeführt wurden.
Um dieses Handle abzurufen, muss eine Anwendung zunächst ein Hashobjekt mit CryptCreateHash erstellen und dann die Basisdaten dem Hashobjekt mit CryptHashData hinzufügen. Dieser Prozess wird unter Hashes und digitale Signaturen ausführlich beschrieben.
[in] dwFlags
Gibt den Typ des generierten Schlüssels an.
Die Größen eines Sitzungsschlüssels können festgelegt werden, wenn der Schlüssel generiert wird. Die Schlüsselgröße, die die Länge des Schlüsselmoduls in Bits darstellt, wird mit den oberen 16 Bits dieses Parameters festgelegt. Wenn also ein 128-Bit-RC4-Sitzungsschlüssel generiert werden soll, wird der Wert 0x00800000 mit jedem anderen vordefinierten dwFlags-Wert mit einem bitweisen OR-Vorgang kombiniert. Aufgrund geänderter Exportsteuerungseinschränkungen können sich die Standard-CSP- und Standardschlüssellänge zwischen Betriebssystemversionen ändern. Es ist wichtig, dass sowohl die Verschlüsselung als auch die Entschlüsselung denselben CSP verwenden und die Schlüssellänge explizit mithilfe des dwFlags-Parameters festgelegt wird, um die Interoperabilität auf verschiedenen Betriebssystemplattformen sicherzustellen.
Die unteren 16 Bits dieses Parameters können null sein, oder Sie können eines oder mehrere der folgenden Flags angeben, indem Sie den bitweisen OR-Operator verwenden, um sie zu kombinieren.
| Wert | Bedeutung |
|---|---|
|
Wenn ein Sitzungsschlüssel aus einem Hashwert erstellt wird, gibt es in der Regel eine Reihe von Restbits. Wenn der Hashwert beispielsweise 128 Bits und der Sitzungsschlüssel 40 Bits beträgt, bleiben 88 Bit übrig.
Wenn dieses Flag festgelegt ist, wird dem Schlüssel basierend auf den nicht verwendeten Hashwertbits ein Salzwert zugewiesen. Sie können diesen Salzwert mithilfe der CryptGetKeyParam-Funktion abrufen, wobei der dwParam-Parameter auf KP_SALT festgelegt ist. Wenn dieses Flag nicht festgelegt ist, erhält der Schlüssel den Salzwert 0. Wenn Schlüssel mit nichtzero salt-Werten exportiert werden (mithilfe von CryptExportKey), muss auch der Salzwert abgerufen und mit dem Schlüsselblob beibehalten werden. |
|
Wenn dieses Flag festgelegt ist, kann der Sitzungsschlüssel über die CryptExportKey-Funktion aus dem CSP in ein Schlüsselblob übertragen werden. Da Schlüssel in der Regel exportierbar sein müssen, sollte dieses Flag in der Regel festgelegt werden.
Wenn dieses Flag nicht festgelegt ist, kann der Sitzungsschlüssel nicht exportiert werden. Dies bedeutet, dass der Schlüssel nur innerhalb der aktuellen Sitzung verfügbar ist, und nur die Anwendung, von der er erstellt wurde, kann ihn verwenden. Dieses Flag gilt nicht für öffentliche/private Schlüsselpaare. |
|
Dieses Flag gibt an, dass ein Wert ohne Salz für einen symmetrischen 40-Bit-Schlüssel zugewiesen wird. Weitere Informationen finden Sie unter Salt-Wert-Funktionalität. |
|
Einige CSPs verwenden Sitzungsschlüssel, die von mehreren Hashwerten abgeleitet werden. In diesem Fall muss CryptDeriveKey mehrmals aufgerufen werden.
Wenn dieses Flag festgelegt ist, wird kein neuer Sitzungsschlüssel generiert. Stattdessen wird der von phKey angegebene Schlüssel geändert. Das genaue Verhalten dieses Flags hängt vom Typ des generierten Schlüssels und vom jeweiligen verwendeten CSP ab. Microsoft-Kryptografiedienstanbieter ignorieren dieses Flag. |
|
Dieses Flag wird nur bei Schannel-Anbietern verwendet. Wenn dieses Flag festgelegt ist, ist der zu generierende Schlüssel ein Serverschreibschlüssel. Andernfalls handelt es sich um einen Clientschreibschlüssel. |
[in, out] phKey
Ein Zeiger auf eine HCRYPTKEY-Variable , um die Adresse des Handles des neu generierten Schlüssels zu empfangen. Wenn Sie die Verwendung des Schlüssels abgeschlossen haben, lassen Sie das Handle los, indem Sie die Funktion CryptDestroyKey aufrufen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Die von "NTE" vorangestellten Fehlercodes werden vom verwendeten CSP generiert. Einige mögliche Fehlercodes sind in der folgenden Tabelle aufgeführt.
| Rückgabecode | Beschreibung |
|---|---|
|
Einer der Parameter gibt ein ungültiges Handle an. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein nicht gültiger Zeiger. |
|
Der Algid-Parameter gibt einen Algorithmus an, den dieser CSP nicht unterstützt. |
|
Der dwFlags-Parameter enthält einen wert, der ungültig ist. |
|
Der hBaseData-Parameter enthält kein gültiges Handle für ein Hashobjekt. |
|
Es wurde versucht, einem Hashobjekt Daten hinzuzufügen, das bereits als "abgeschlossen" gekennzeichnet ist. |
|
Der hProv-Parameter enthält kein gültiges Kontexthandle. |
|
Die Funktion ist auf unerwartete Weise fehlgeschlagen. |
|
Der Anbieter konnte die Aktion nicht ausführen, da der Kontext als unbeaufsichtigt abgerufen wurde. |
Hinweise
Wenn Schlüssel für symmetrischeBlockchiffren generiert werden, wird der Schlüssel standardmäßig im CBC-Modus ( Cipher Block Chaining ) mit einem Initialisierungsvektor von null eingerichtet. Dieser Verschlüsselungsmodus bietet eine gute Standardmethode für die Massenverschlüsselung von Daten. Um diese Parameter zu ändern, verwenden Sie die Funktion CryptSetKeyParam .
Die CryptDeriveKey-Funktion vervollständigt den Hash. Nachdem CryptDeriveKey aufgerufen wurde, können dem Hash keine weiteren Daten hinzugefügt werden. Zusätzliche Aufrufe von CryptHashData oder CryptHashSessionKey schlagen fehl. Nachdem die Anwendung mit dem Hash abgeschlossen ist, muss CryptDestroyHash aufgerufen werden, um das Hashobjekt zu zerstören.
Um eine geeignete Schlüssellänge auszuwählen, werden die folgenden Methoden empfohlen.
- Rufen Sie CryptGetProvParam mit PP_ENUMALGS_EX auf, um die vom CSP unterstützten Algorithmen aufzulisten und die maximale und minimale Schlüssellänge für jeden Algorithmus abzurufen.
- Verwenden Sie die Mindest- und Maximallänge, um eine geeignete Schlüssellänge auszuwählen. Es ist nicht immer ratsam, die maximale Länge zu wählen, da dies zu Leistungsproblemen führen kann.
- Nachdem die gewünschte Schlüssellänge ausgewählt wurde, verwenden Sie die oberen 16 Bits des dwFlags-Parameters , um die Schlüssellänge anzugeben.
- Bilden Sie einen 64-Byte-Puffer, indem Sie die Konstante 0x36 64 Mal wiederholen. Lassen Sie k die Länge des Hashwerts sein, der durch den Eingabeparameter hBaseData dargestellt wird. Legen Sie die ersten k Bytes des Puffers auf das Ergebnis eines XOR-Vorgangs der ersten k Bytes des Puffers mit dem Hashwert fest, der durch den Eingabeparameter hBaseData dargestellt wird.
- Bilden Sie einen 64-Byte-Puffer, indem Sie die Konstante 0x5C 64 Mal wiederholen. Legen Sie die ersten k Bytes des Puffers auf das Ergebnis eines XOR-Vorgangs der ersten k Bytes des Puffers mit dem Hashwert fest, der durch den Eingabeparameter hBaseData dargestellt wird.
- Hashen Sie das Ergebnis von Schritt 1, indem Sie denselben Hashalgorithmus wie zum Berechnen des Hashwerts verwenden, der durch den hBaseData-Parameter dargestellt wird.
- Hashen Sie das Ergebnis von Schritt 2, indem Sie denselben Hashalgorithmus verwenden, der zum Berechnen des Hashwerts verwendet wird, der durch den hBaseData-Parameter dargestellt wird.
- Verketten Sie das Ergebnis von Schritt 3 mit dem Ergebnis von Schritt 4.
- Verwenden Sie die ersten n Bytes des Ergebnisses von Schritt 5 als abgeleiteten Schlüssel.
In der folgenden Tabelle sind Mindest-, Standard- und maximale Schlüssellängen für Sitzungsschlüssel nach Algorithmus und Anbieter aufgeführt.
| Anbieter | Algorithmen | Minimale Schlüssellänge | Standardschlüssellänge | Maximale Schlüssellänge |
|---|---|---|---|---|
| MS Base | RC4 und RC2 | 40 | 40 | 56 |
| MS Base | DES | 56 | 56 | 56 |
| MS Erweitert | RC4 und RC2 | 40 | 128 | 128 |
| MS Erweitert | DES | 56 | 56 | 56 |
| MS Erweitert | 3DES 112 | 112 | 112 | 112 |
| MS Erweitert | 3DES | 168 | 168 | 168 |
| MS Strong | RC4 und RC2 | 40 | 128 | 128 |
| MS Strong | DES | 56 | 56 | 56 |
| MS Strong | 3DES 112 | 112 | 112 | 112 |
| MS Strong | 3DES | 168 | 168 | 168 |
| DSS/DH-Basis | RC4 und RC2 | 40 | 40 | 56 |
| DSS/DH-Basis | Cylink MEK | 40 | 40 | 40 |
| DSS/DH-Basis | DES | 56 | 56 | 56 |
| DSS/DH Enh | RC4 und RC2 | 40 | 128 | 128 |
| DSS/DH Enh | Cylink MEK | 40 | 40 | 40 |
| DSS/DH Enh | DES | 56 | 56 | 56 |
| DSS/DH Enh | 3DES 112 | 112 | 112 | 112 |
| DSS/DH Enh | 3DES | 168 | 168 | 168 |
Beispiele
Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Ableiten eines Sitzungsschlüssels aus einem Kennwort.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.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