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.

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.

[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.

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.

[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.

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

Siehe auch

CryptAcquireContext-

CryptDestroyKey-

CryptExportKey-

CryptGetKeyParam

CryptImportKey-

CryptSetKeyParam-

Schlüsselgenerierung und Exchange-Funktionen

Threadingprobleme mit Kryptografiedienstanbietern