CryptDeriveKey-Funktion (wincrypt.h)
Diese Funktion ist identisch mit CryptGenKey, mit der Ausnahme, dass die generierten Sitzungsschlüssel von Basisdaten abgeleitet werden, anstatt zufällig zu sein. CryptDeriveKey- kann nur zum Generieren von Sitzungsschlüsseln verwendet werden. Es kann nicht öffentliche/private Schlüsselpaaregeneriert werden.
Ein Handle für den Sitzungsschlüssel wird im phKey--Parameter 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 CryptAcquireContexterstellt wurde.
[in] Algid
Eine ALG_ID Struktur, die die symmetrische Verschlüsselung Algorithmus identifiziert, für den der Schlüssel generiert werden soll. Die verfügbaren Algorithmen unterscheiden sich wahrscheinlich für jeden CSP. 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 zu einem Hashobjekt, das die genauen Basisdaten einspeist.
Um dieses Handle zu erhalten, muss eine Anwendung zuerst ein Hashobjekt mit CryptCreateHash erstellen und dann die Basisdaten zum Hashobjekt mit CryptHashData-hinzufügen. Dieser Prozess wird in Hashes und digitalen Signaturenausfü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 allen anderen dwFlags vordefinierten Wert mit einem bitweisenODER-Vorgang kombiniert. Aufgrund der Änderung der Exportsteuerungseinschränkungen kann sich der Standard-CSP und die Standardlänge Schlüssellänge zwischen Betriebssystemversionen ändern. Es ist wichtig, dass sowohl die Verschlüsselung als auch die Entschlüsselung denselben CSP verwenden und dass die Schlüssellänge explizit mit dem dwFlags Parameter festgelegt wird, um die Interoperabilität auf verschiedenen Betriebssystemplattformen sicherzustellen.
Die unteren 16 Bit dieses Parameters können null sein, oder Sie können eine oder mehrere der folgenden Flags angeben, indem Sie den bitweisenODER--Operator verwenden, um sie zu kombinieren.
| Wert | Bedeutung |
|---|---|
|
Wenn ein Sitzungsschlüssel aus einem Hash- Wert hergestellt wird, gibt es eine Reihe von Linksoverbits. Wenn der Hashwert beispielsweise 128 Bit beträgt und der Sitzungsschlüssel 40 Bit beträgt, verbleiben 88 Bit.
Wenn dieses Flag festgelegt ist, wird dem Schlüssel basierend auf den nicht verwendeten Hashwertbits ein Salzwert zugewiesen. Sie können diesen Salzwert abrufen, indem Sie die CryptGetKeyParam--Funktion verwenden, wobei der dwParam Parameter auf KP_SALT festgelegt ist. Wenn dieses Kennzeichen nicht festgelegt ist, erhält der Schlüssel einen Salzwert von Null. Wenn Schlüssel mit nichtzero-Salzwerten exportiert werden (mithilfe von CryptExportKey), muss der Salzwert auch mit dem Schlüssel-BLOB-abgerufen und beibehalten werden. |
|
Wenn dieses Kennzeichen festgelegt ist, kann der Sitzungsschlüssel über die CryptExportKey--Funktion aus dem CSP in einen Schlüssel-BLOB übertragen werden. Da Schlüssel im Allgemeinen 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, die sie erstellt hat, sie verwenden kann. Dieses Kennzeichen gilt nicht für öffentliche/private Schlüsselpaare. |
|
Dieses Kennzeichen gibt an, dass ein Salzwert, für einen symmetrischen symmetrischen Schlüsselzugeordnet wird. Weitere Informationen finden Sie unter Salt Value Functionality. |
|
Einige CSPs verwenden Sitzungsschlüssel, die von mehreren Hashwerten abgeleitet werden. Wenn dies der Fall ist, muss CryptDeriveKey- mehrmals aufgerufen werden.
Wenn dieses Flag festgelegt ist, wird kein neuer Sitzungsschlüssel generiert. Stattdessen wird der durch phKey angegebene Schlüssel geändert. Das genaue Verhalten dieses Kennzeichens hängt vom Typ des zu generierenden Schlüssels und vom verwendeten CSP ab. Diese Kennzeichnung wird von Microsoft-Kryptografiedienstanbietern ignoriert. |
|
Dieses Flag wird nur für Schannel Anbieter verwendet. Wenn dieses Kennzeichen 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 CryptDestroyKey--Funktion aufrufen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.
Wenn die Funktion fehlschlägt, wird null (FALSE) zurückgegeben. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.
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 am häufigsten ein ungültiger Zeiger. |
|
Der Algid Parameter gibt einen Algorithmus an, den dieser CSP nicht unterstützt. |
|
Der dwFlags Parameter enthält einen ungültigen Wert. |
|
Der hBaseData--Parameter enthält kein gültiges Handle für ein Hashobjekt. |
|
Es wurde versucht, Daten zu einem Hashobjekt hinzuzufügen, das bereits als "fertig" gekennzeichnet ist. |
|
Der hProv--Parameter enthält kein gültiges Kontexthandle. |
|
Die Funktion konnte auf unerwartete Weise nicht ausgeführt werden. |
|
Der Anbieter konnte die Aktion nicht ausführen, da der Kontext im Hintergrund abgerufen wurde. |
Bemerkungen
Wenn Schlüssel für symmetrischenBlockchiffregeneriert werden, wird der Schlüssel standardmäßig im Verschlüsselungsblockverkettungsmodus (CBC) mit einem Initialisierungsvektor von Null eingerichtet. Dieser Verschlüsselungsmodus bietet eine gute Standardmethode für massenverschlüsselte Daten. Verwenden Sie zum Ändern dieser Parameter die CryptSetKeyParam--Funktion.
Die CryptDeriveKey--Funktion schließt die Hash-ab. Nachdem CryptDeriveKey aufgerufen wurde, können dem Hash keine weiteren Daten hinzugefügt werden. Weitere Aufrufe von CryptHashData oder CryptHashSessionKey fehl. Nachdem die Anwendung mit dem Hash abgeschlossen wurde, muss CryptDestroyHash aufgerufen werden, um das Hashobjekt zu zerstören.
Zum Auswählen einer geeigneten Schlüssellängewerden die folgenden Methoden empfohlen.
- Rufen Sie CryptGetProvParam- mit PP_ENUMALGS_EX auf, um die vom CSP unterstützten Algorithmen auflisten und maximale und minimale Schlüssellängen für jeden Algorithmus zu erhalten.
- Verwenden Sie die mindesten und maximalen Längen, um eine entsprechende 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 Bit des dwFlags Parameter, 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 das erste k Bytes des Puffers auf das Ergebnis eines XOR- Vorgangs des ersten k Bytes des Puffers mit dem Hashwert fest, der durch den Eingabeparameter hBaseDatadargestellt wird.
- Bilden Sie einen 64-Byte-Puffer, indem Sie die Konstante 0x5C 64 Mal wiederholen. Legen Sie das erste k Bytes des Puffers auf das Ergebnis eines XOR- Vorgangs des ersten k Bytes des Puffers mit dem Hashwert fest, der durch den Eingabeparameter hBaseDatadargestellt wird.
- Hashen Sie das Ergebnis von Schritt 1, indem Sie denselben Hashalgorithmus verwenden, mit dem der Hashwert berechnet wird, der durch den hBaseData--Parameter dargestellt wird.
- Hashen Sie das Ergebnis von Schritt 2, indem Sie denselben Hashalgorithmus verwenden, mit dem der Hashwert berechnet 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 | Standardtastenlänge | Maximale Schlüssellänge |
|---|---|---|---|---|
| MS-Basis | RC4 und RC2 | 40 | 40 | 56 |
| MS-Basis | DES | 56 | 56 | 56 |
| MS Enhanced | RC4 und RC2 | 40 | 128 | 128 |
| MS Enhanced | DES | 56 | 56 | 56 |
| MS Enhanced | 3DES 112 | 112 | 112 | 112 |
| MS Enhanced | 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 von einem Kennwort-.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | wincrypt.h |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |