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 kryptografischen Dienstanbieter (CSP), der durch einen Aufruf von CryptAcquireContexterstellt 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 verwendeter CSP.
Informationen zu ALG_ID Werten für die Verwendung mit dem Microsoft Base Cryptographic Provider finden Sie unter Base Provider-Algorithmen.
Informationen zu ALG_ID Werten, die mit dem Microsoft Strong Cryptographic Provider oder dem Erweiterten Kryptografieanbieter von Microsoft verwendet werden sollen, finden Sie unter Erweiterte Anbieteralgorithmen.
Verwenden Sie für einen Diffie-Hellman CSP einen der folgenden Werte.
| Wert | Bedeutung |
|---|---|
|
Gibt einen "Ephemeral" Diffie-Hellman Taste an. |
|
Gibt einen Diffie-Hellman schlüssel "Speichern und Weiterleiten" an. |
Neben dem Generieren von Sitzungsschlüsseln für symmetrischen Algorithmenkann diese Funktion auch öffentlichen/privaten Schlüsselpaaregenerieren. Jeder CryptoAPI-Client verfügt im Allgemeinen über 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üssels Exchange Keys 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 2.048-Bit-RSA-Signaturschlüssel generiert werden soll, wird der Wert 0x08000000 mit allen anderen dwFlags vordefinierten Wert mit einem bitweisenOR--Vorgang kombiniert. Die oberen 16 Bits von 0x08000000 sind 0x0800 oder dezimal 2.048. Der wert RSA1024BIT_KEY kann verwendet werden, um einen 1024-Bit-RSA-Schlüssel anzugeben.
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.
Insbesondere ist der standardmäßige RSA Full Cryptographic Service Provider der Microsoft RSA Strong Cryptographic Provider. Der standardmäßige DSS-Signatur-Diffie-Hellman Kryptografiedienstanbieter ist der microsoft Enhanced DSS Diffie-Hellman Kryptografieanbieter. Jeder dieser CSPs verfügt über eine standardmäßige 128-Bit-symmetrische Schlüssellänge für RC2 und RC4 und eine 1.024-Bit-Standardschlüssellänge für Public Key-Algorithmen.
Wenn die oberen 16 Bit null sind, wird die Standardschlüsselgröße generiert. Wenn ein Schlüssel, der größer als das Maximum oder kleiner als das Minimum ist, angegeben ist, schlägt der Aufruf mit dem ERROR_INVALID_PARAMETER Code fehl.
In der folgenden Tabelle sind Mindest-, Standard- und maximale Signatur- und Austauschschlüssellängen aufgeführt, die mit Windows XP beginnen.
| Schlüsseltyp und Anbieter | Mindestlänge | Standardlänge | Maximale Länge |
|---|---|---|---|
|
RSA-Basisanbieter Signaturen und ExchangeKeys |
384 | 512 | 16,384 |
|
RSA Starke und erweiterte 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 |
|
DSS/DH Enhanced Providers Signaturschlüssel |
512 | 1,024 | 1,024 |
|
DSS/DH Enhanced Providers 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 werden, 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 CryptDestroyKeygeschlossen wird. Auf diese Weise können neu generierte Schlüssel beim Erstellen der Archivierung oder Schlüsselwiederherstellung exportiert werden. Nachdem das Handle geschlossen wurde, kann der Schlüssel nicht mehr exportiert werden. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Wenn dieses Kennzeichen 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 Kennzeichen nicht festgelegt ist, erhält der Schlüssel einen Salzwert von Null. Wenn Schlüssel mit Nichtzerosalzwerten exportiert werden (über CryptExportKey), muss auch der Salzwert abgerufen und mit dem SCHLÜSSEL BLOB-erhalten und beibehalten werden. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Wenn dieses Kennzeichen festgelegt ist, kann der Schlüssel über die CryptExportKey--Funktion aus dem CSP in einen Schlüssel-BLOB übertragen werden. Da Sitzungsschlüssel im Allgemeinen exportierbar sein müssen, sollte dieses Flag in der Regel festgelegt werden, wenn sie erstellt werden.
Wenn dieses Flag nicht festgelegt ist, kann der Schlüssel nicht exportiert werden. Bei einem Sitzungsschlüssel bedeutet dies, dass der Schlüssel nur innerhalb der aktuellen Sitzung verfügbar ist und nur die Anwendung, die sie erstellt hat, sie verwenden kann. Bei einem paar öffentlicher/privater Schlüsselbedeutet dies, dass der private Schlüssel nicht transportiert oder gesichert werden kann. Dieses Kennzeichen gilt nur für Sitzungsschlüssel und private Schlüssel-BLOBs. Sie gilt nicht für öffentliche Schlüssel, die immer exportiert werden können. |
|
Dieses Kennzeichen gibt einen starken Schlüsselschutz an. Wenn dieses Kennzeichen 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 Kennzeichen wird nur von den csPs verwendet, die von Microsoft bereitgestellt werden. CsPs von Drittanbietern definieren ihr eigenes Verhalten für starken Schlüsselschutz. Wenn Sie dieses Kennzeichen angeben, wird dasselbe Ergebnis wie das Aufrufen dieser Funktion mit dem CRYPT_USER_PROTECTED Flag verursacht, wenn in der Systemregistrierung ein starker Schlüsselschutz angegeben wird. 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 Kennzeichen wird nicht verwendet. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Dieses Kennzeichen gibt an, dass ein Salzwert, für einen vierzig Bit-symmetrischen Schlüsselzugewiesen wird. Weitere Informationen finden Sie unter Salt Value Functionality. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Dieses Kennzeichen gibt eine anfängliche Diffie-Hellman- oder DSS-Schlüsselgenerierung an. Dieses Kennzeichen ist nur bei Diffie-Hellman und DSS-CSPs hilfreich. Bei Verwendung wird eine Standardschlüssellänge verwendet, es sei denn, eine Schlüssellänge wird in den oberen 16 Bits des dwFlags Parameter angegeben. Wenn Parameter mit Schlüssellängen für einen PREGEN-Diffie-Hellman oder DSS-Schlüssel mit CryptSetKeyParamfestgelegt werden, müssen die Schlüssellängen mit der hier festgelegten Schlüssellänge kompatibel sein. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Dieses Kennzeichen wird nicht verwendet. |
|
Wenn dieses Kennzeichen 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 Flagsatz geöffnet wurde, führt die Verwendung dieses Flags zu einem Fehler, und der letzte Fehler wird auf NTE_SILENT_CONTEXT festgelegt. |
|
Dieses Kennzeichen wird nicht verwendet. |
[out] phKey
Adresse, an die die Funktion das Handle des neu generierten Schlüssels kopiert. Wenn Sie mit der Verwendung des Schlüssels fertig sind, löschen Sie den Handle auf den Schlüssel, indem Sie die CryptDestroyKey--Funktion aufrufen.
Rückgabewert
Gibt "nonzero" zurück, wenn dies erfolgreich oder null ist.
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 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 in Verschlüsselungsblockverkett ungsmodus (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.
Zum Auswählen einer geeigneten Schlüssellängewerden die folgenden Methoden empfohlen:
- Auflisten der Algorithmen, die vom CSP unterstützt werden, und erhalten für jeden Algorithmus maximale und minimale Schlüssellängen. Rufen Sie dazu CryptGetProvParam- mit PP_ENUMALGS_EX auf.
- 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.
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 |
|---|---|
| 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 |