CryptGenKey-Funktion (wincrypt.h)
Die aufrufende Anwendung muss beim Aufrufen dieser Funktion den Algorithmus angeben. Da dieser Algorithmustyp mit dem Schlüssel gebündelt bleibt, muss die Anwendung den Algorithmus später nicht angeben, wenn die tatsächlichen kryptografischen Vorgänge ausgeführt werden.
Syntax
BOOL CryptGenKey(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
Parameter
[in] hProv
Ein Handle für einen Kryptografiedienstanbieter (Cryptographic Service Provider , CSP), der durch einen Aufruf von CryptAcquireContext erstellt wurde.
[in] Algid
Ein ALG_ID Wert, der den Algorithmus identifiziert, für den der Schlüssel generiert werden soll. Die Werte für diesen Parameter variieren je nach verwendetem CSP.
Informationen zu ALG_ID Werten, die mit dem Microsoft Base-Kryptografieanbieter verwendet werden sollen, finden Sie unter Basisanbieteralgorithmen.
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.
Verwenden Sie für einen Diffie-Hellman CSP einen der folgenden Werte.
| Wert | Bedeutung |
|---|---|
|
Gibt einen "kurzlebigen" Diffie-Hellman Schlüssel an. |
|
Gibt einen "Store and Forward" Diffie-Hellman Schlüssel an. |
Neben der Generierung von Sitzungsschlüsseln für symmetrische Algorithmen kann diese Funktion auch öffentliche/private Schlüsselpaare generieren. Jeder CryptoAPI-Client besitzt im Allgemeinen zwei öffentliche/private Schlüsselpaare. Um eines dieser Schlüsselpaare zu generieren, legen Sie den Algid-Parameter auf einen der folgenden Werte fest.
| Wert | Bedeutung |
|---|---|
|
Schlüsselaustausch |
|
Digitale Signatur |
[in] dwFlags
Gibt den Typ des generierten Schlüssels an. Die Größen eines Sitzungsschlüssels, RSA-Signaturschlüssels und RSA-Schlüsselaustauschschlüssels können beim Generieren des Schlüssels festgelegt werden. 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 2.048-Bit-RSA-Signaturschlüssel generiert werden soll, wird der Wert 0x08000000 mit jedem anderen vordefinierten dwFlags-Wert mit einem bitweisen OR-Vorgang kombiniert. Die oberen 16 Bits von 0x08000000 sind 0x0800 oder dezimal 2.048. Der RSA1024BIT_KEY Wert kann verwendet werden, um einen 1024-Bit-RSA-Schlüssel anzugeben.
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.
Insbesondere ist der standardmäßige vollständige RSA-Kryptografiedienstanbieter der Microsoft RSA Strong Cryptographic Provider. Der Standardmäßige DSS-Signatur-Diffie-Hellman Kryptografiedienstanbieter ist der microsoft Enhanced DSS Diffie-Hellman Cryptographic Provider. Jede dieser CSPs hat eine standardmäßige symmetrische Schlüssellänge von 128 Bit für RC2 und RC4 und eine Standardschlüssellänge von 1.024 Bit für Algorithmen mit öffentlichem Schlüssel.
Wenn die oberen 16 Bits 0 sind, wird die Standardschlüsselgröße generiert. Wenn ein Schlüssel angegeben wird, der größer als das Maximum oder kleiner als das Minimum ist, schlägt der Aufruf mit dem ERROR_INVALID_PARAMETER-Code fehl.
In der folgenden Tabelle sind mindeste, standard- und maximale Signatur- und Austauschschlüssellängen ab Windows XP aufgeführt.
| Schlüsseltyp und -anbieter | Mindestlänge | Standardlänge | Maximale Länge |
|---|---|---|---|
|
RSA-Basisanbieter Signatur und ExchangeKeys |
384 | 512 | 16.384 |
|
Starke und erweiterte RSA-Anbieter Signatur- und Exchange-Schlüssel |
384 | 1\.024 | 16.384 |
|
DSS-Basisanbieter Signaturschlüssel |
512 | 1\.024 | 1\.024 |
|
DSS-Basisanbieter Exchange-Schlüssel |
Nicht zutreffend | Nicht zutreffend | Nicht zutreffend |
|
DSS/DH-Basisanbieter Signaturschlüssel |
512 | 1\.024 | 1\.024 |
|
DSS/DH-Basisanbieter Exchange-Schlüssel |
512 | 512 | 1\.024 |
|
Erweiterte DSS/DH-Anbieter Signaturschlüssel |
512 | 1\.024 | 1\.024 |
|
Erweiterte DSS/DH-Anbieter Exchange-Schlüssel |
512 | 1\.024 | 4\.096 |
Informationen zu Sitzungsschlüssellängen finden Sie unter CryptDeriveKey.
Weitere Informationen zu Schlüsseln, die mit Microsoft-Anbietern generiert wurden, finden Sie unter Microsoft Cryptographic Service Providers.
Die unteren 16 Bits dieses Parameters können null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Wenn dieses Flag festgelegt ist, kann der Schlüssel exportiert werden, bis sein Handle durch einen Aufruf von CryptDestroyKey geschlossen wird. Dadurch können neu generierte Schlüssel bei der Erstellung für die Archivierung oder Schlüsselwiederherstellung exportiert werden. Nachdem der Handle geschlossen wurde, kann der Schlüssel nicht mehr exportiert werden. |
|
Dieses Flag wird nicht verwendet. |
|
Wenn dieses Flag festgelegt ist, wird dem Schlüssel automatisch ein zufälliger 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 nonzero salt-Werten exportiert werden (über CryptExportKey), muss auch der Salzwert abgerufen und mit dem Schlüsselblob beibehalten werden. |
|
Dieses Flag wird nicht verwendet. |
|
Wenn dieses Flag festgelegt ist, kann der Schlüssel mithilfe der CryptExportKey-Funktion aus dem CSP in ein Schlüsselblob übertragen werden. Da Sitzungsschlüssel in der Regel exportierbar sein müssen, sollte dieses Flag normalerweise beim Erstellen festgelegt werden.
Wenn dieses Flag nicht festgelegt ist, kann der Schlüssel nicht exportiert werden. Für einen Sitzungsschlüssel bedeutet dies, dass der Schlüssel nur innerhalb der aktuellen Sitzung verfügbar ist und nur die Anwendung, die ihn erstellt hat, ihn verwenden kann. Für ein öffentliches/privates Schlüsselpaar bedeutet dies, dass der private Schlüssel nicht transportiert oder gesichert werden kann. Dieses Flag gilt nur für Sitzungsschlüssel und private Schlüssel-BLOBs. Sie gilt nicht für öffentliche Schlüssel, die immer exportierbar sind. |
|
Dieses Flag gibt starken Schlüsselschutz an. Wenn dieses Flag festgelegt ist, wird der Benutzer aufgefordert, beim Erstellen des Schlüssels ein Kennwort für den Schlüssel einzugeben. Der Benutzer wird aufgefordert, das Kennwort einzugeben, wenn dieser Schlüssel verwendet wird.
Dieses Flag wird nur von den CSPs verwendet, die von Microsoft bereitgestellt werden. Drittanbieter-CSPs definieren ihr eigenes Verhalten für starken Schlüsselschutz. Die Angabe dieses Flags führt zum gleichen Ergebnis wie das Aufrufen dieser Funktion mit dem CRYPT_USER_PROTECTED-Flag , wenn in der Systemregistrierung der Schutz vor starkem Schlüssel angegeben ist. Wenn dieses Flag angegeben ist und das Anbieterhandle im hProv-Parameter mithilfe des CRYPT_VERIFYCONTEXT - oder CRYPT_SILENT-Flags erstellt wurde, legt diese Funktion den letzten Fehler auf NTE_SILENT_CONTEXT fest und gibt null zurück. Windows Server 2003 und Windows XP: Dieses Flag wird nicht unterstützt. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag gibt an, dass ein Wert ohne Salz für einen symmetrischen Vierzig-Bit-Schlüssel zugewiesen wird. Weitere Informationen finden Sie unter Salt-Wert-Funktionalität. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag gibt eine anfängliche Diffie-Hellman- oder DSS-Schlüsselgenerierung an. Dieses Flag ist nur bei Diffie-Hellman- und DSS-CSPs nützlich. Bei Verwendung wird eine Standardschlüssellänge verwendet, es sei denn, in den oberen 16 Bits des dwFlags-Parameters wird eine Schlüssellänge angegeben. Wenn Parameter, die Schlüssellängen umfassen, für einen PREGEN-Diffie-Hellman- oder DSS-Schlüssel mithilfe von CryptSetKeyParam festgelegt werden, müssen die Schlüssellängen mit dem hier festgelegten Schlüssellängensatz kompatibel sein. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag wird nicht verwendet. |
|
Wenn dieses Flag festgelegt ist, wird der Benutzer über ein Dialogfeld oder eine andere Methode benachrichtigt, wenn bestimmte Aktionen versuchen, diesen Schlüssel zu verwenden. Das genaue Verhalten wird durch den verwendeten CSP angegeben. Wenn der Anbieterkontext mit dem CRYPT_SILENT-Flag geöffnet wurde, verursacht die Verwendung dieses Flags einen Fehler, und der letzte Fehler wird auf NTE_SILENT_CONTEXT festgelegt. |
|
Dieses Flag wird nicht verwendet. |
[out] phKey
Adresse, an die die Funktion das Handle des neu generierten Schlüssels kopiert. Wenn Sie die Verwendung des Schlüssels abgeschlossen haben, löschen Sie das Handle für den Schlüssel, indem Sie die Funktion CryptDestroyKey aufrufen.
Rückgabewert
Gibt nonzero zurück, wenn der Vorgang erfolgreich war oder andernfalls null.
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 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 .
Um eine geeignete Schlüssellänge auszuwählen, werden die folgenden Methoden empfohlen:
- Führen Sie die vom CSP unterstützten Algorithmen auf, und rufen Sie die maximale und minimale Schlüssellänge für jeden Algorithmus ab. Rufen Sie hierzu CryptGetProvParam mit PP_ENUMALGS_EX auf.
- 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.
Beispiele
Das folgende Beispiel zeigt die Erstellung eines zufälligen Sitzungsschlüssels. Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel C-Programm: Verschlüsseln einer Datei. Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Entschlüsseln einer Datei.
//-------------------------------------------------------------------
// Declare the handle to the key.
HCRYPTKEY hKey;
//-------------------------------------------------------------------
// This example assumes that a cryptographic context
// has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
// Create a random session key.
if(CryptGenKey(
hCryptProv,
ENCRYPT_ALGORITHM,
KEYLENGTH | CRYPT_EXPORTABLE,
&hKey))
{
printf("A session key has been created.\n");
}
else
{
printf("Error during CryptGenKey.\n");
exit(1);
}
//-------------------------------------------------------------------
// The key created can be exported into a key BLOB that can be
// written to a file.
// ...
// When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
printf("Error during CryptDestroyKey.\n");
exit(1);
}
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