CryptSetKeyParam-Funktion (wincrypt.h)
Der Microsoft Base-Kryptografieanbieter lässt keine Einstellungswerte für Schlüsselaustausch- oder Signaturschlüssel zu. Benutzerdefinierte Anbieter können jedoch Werte definieren, die für ihre Schlüssel festgelegt werden können.
Syntax
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
Parameter
[in] hKey
Ein Handle für den Schlüssel, für den Werte festgelegt werden sollen.
[in] dwParam
Die folgenden Tabellen enthalten vordefinierte Werte, die verwendet werden können.
Für alle Schlüsseltypen kann dieser Parameter einen der folgenden Werte enthalten.
| Wert | Bedeutung |
|---|---|
|
pbData verweist auf eine entsprechende ALG_ID. Dies wird beim Austauschen von Sitzungsschlüsseln mit microsoft Base Digital Signature Standard (DSS), Diffie-Hellman Cryptographic Provider oder kompatiblen CSPs verwendet. Nachdem ein Schlüssel mit der CryptImportKey-Funktion vereinbart wurde, wird der Sitzungsschlüssel für die Verwendung aktiviert, indem der Algorithmustyp festgelegt wird. |
|
pbData ist die Adresse eines Puffers, der das X.509-Zertifikat enthält, das mithilfe von Distinguished Encoding Rules (DER) codiert wurde. Der öffentliche Schlüssel im Zertifikat muss mit dem entsprechenden Signatur- oder Austauschschlüssel übereinstimmen. |
|
pbData verweist auf einen DWORD-Wert , der null oder mehr Berechtigungsflags angibt. Eine Beschreibung dieser Flags finden Sie unter CryptGetKeyParam. |
|
pbData verweist auf ein BYTE-Array , das einen neuen Salzwert angibt, der teil des Sitzungsschlüssels werden soll. Die Größe des Salzwerts hängt vom verwendeten CSP ab. Bevor Sie diesen Wert festlegen, bestimmen Sie die Größe des Salzwerts, indem Sie die CryptGetKeyParam-Funktion aufrufen. Salzwerte werden verwendet, um die Sitzungsschlüssel eindeutiger zu machen, was Wörterbuchangriffe erschwert. Der Salzwert ist standardmäßig 0 für Microsoft Base Cryptographic Provider. |
|
pbData verweist auf eine CRYPT_INTEGER_BLOB-Struktur , die das Salz enthält. Weitere Informationen finden Sie unter Angeben eines Salzwerts. |
Wenn ein DSS-Schlüssel ( Digital Signature Standard ) durch den hKey-Parameter angegeben wird, kann der dwParam-Wert auch auf einen der folgenden Werte festgelegt werden.
| Wert | Bedeutung |
|---|---|
|
pbData zeigt aus dem DSS-Schlüssel-BLOB auf den Generator G. Die Daten sind in Form einer CRYPT_INTEGER_BLOB-Struktur , wobei das pbData-Element der Wert und das cbData-Element die Länge des Werts ist. Der Wert wird ohne Headerinformationen und in Little-Endian-Form erwartet. |
|
pbData zeigt auf das Hauptmodul P eines DSS-Schlüsselblobs. Die Daten sind in Form einer CRYPT_INTEGER_BLOB-Struktur . Der pbData-Member ist der Wert, und das cbData-Element ist die Länge des Werts. Der Wert wird ohne Headerinformationen und in Little-Endian-Form erwartet. |
|
pbData zeigt auf den ersten Q eines DSS-Schlüsselblobs. Die Daten sind in Form einer CRYPT_INTEGER_BLOB-Struktur , bei der das pbData-Element der Wert und das cbData-Element die Länge des Werts ist. Der Wert wird ohne Headerinformationen und in Little-Endian-Form erwartet. |
|
Nachdem die P-, Q- und G-Werte festgelegt wurden, kann ein Aufruf, der den KP_X Wert für dwParam und NULL für den pbData-Parameter angibt, an die CryptSetKeyParam-Funktion erfolgen. Dadurch werden die X- und Y-Werte generiert. |
Wenn ein Diffie-Hellman-Algorithmus oder DSA-Schlüssel ( Digital Signature Algorithm ) von hKey angegeben wird, kann der dwParam-Wert auch auf einen der folgenden Werte festgelegt werden.
| Wert | Bedeutung |
|---|---|
|
Legt die Informationen für einen importierten Diffie-Hellman-Schlüssel fest. Der pbData-Parameter ist die Adresse einer CMS_DH_KEY_INFO-Struktur , die die festzulegenden Schlüsselinformationen enthält. |
|
Legt die öffentlichen Parameter (P, Q, G usw.) eines DSS- oder Diffie-Hellman-Schlüssels fest. Das Schlüsselhandle für diesen Schlüssel muss sich im PREGEN-Zustand befinden, der mit dem CRYPT_PREGEN-Flag generiert wird. Der pbData-Parameter muss ein Zeiger auf eine DATA_BLOB Struktur sein, bei der die Daten in dieser Struktur ein DHPUBKEY_VER3 oder DSSPUBKEY_VER3 BLOB sind. Die Funktion kopiert die öffentlichen Parameter aus dieser CRYPT_INTEGER_BLOB Struktur in das Schlüsselhandle. Nach diesem Aufruf sollte der KP_X-Parameterwert mit CryptSetKeyParam verwendet werden, um den tatsächlichen privaten Schlüssel zu erstellen. Der KP_PUB_PARAMS-Parameter wird als ein Aufruf anstelle mehrerer Aufrufe mit den Parameterwerten KP_P, KP_Q und KP_G verwendet. |
Wenn ein Blockchiffresitzungsschlüssel durch den hKey-Parameter angegeben wird, kann der dwParam-Wert auch auf einen der folgenden Werte festgelegt werden.
| Wert | Bedeutung |
|---|---|
|
Dieser Werttyp kann nur mit RC2-Schlüsseln verwendet werden und wurde aufgrund der Implementierung der CryptSetKeyParam-Funktion im erweiterten Kryptografieanbieter von Microsoft vor Windows 2000 hinzugefügt. In der vorherigen Implementierung hatten die RC2-Schlüssel im erweiterten Anbieter eine Stärke von 128 Bit, aber die effektive Schlüssellänge, die zum Erweitern von Schlüsseln in die Schlüsseltabelle verwendet wurde, betrug nur 40 Bit. Dadurch wurde die Stärke des Algorithmus auf 40 Bit reduziert. Um die Abwärtskompatibilität zu gewährleisten, bleibt die vorherige Implementierung unverändert. Die effektive Schlüssellänge kann jedoch mit KP_EFFECTIVE_KEYLEN im CryptSetKeyParam-Aufruf auf größer als 40 Bit festgelegt werden. Die effektive Schlüssellänge wird im pbData-Parameter als Zeiger auf einen DWORD-Wert mit dem effektiven Schlüssellängenwert übergeben. Die minimale effektive Schlüssellänge für den Microsoft Base Cryptographic Provider ist 1, und das Maximum ist 40. Im erweiterten Kryptografieanbieter von Microsoft ist das Minimum eins und das Maximum 1.024. Die Schlüssellänge muss vor dem Verschlüsseln oder Entschlüsseln mit dem Schlüssel festgelegt werden. |
|
Legt die höchste zulässige TLS-Version (Transport Layer Security ) fest. Diese Eigenschaft gilt nur für SSL- und TLS-Schlüssel. Der pbData-Parameter ist die Adresse einer DWORD-Variablen , die die höchste unterstützte TLS-Versionsnummer enthält. |
|
pbData verweist auf ein BYTE-Array , das den Initialisierungsvektor angibt. Dieses Array muss BlockLength/8-Elemente enthalten. Wenn die Blocklänge beispielsweise 64 Bits beträgt, besteht der Initialisierungsvektor aus 8 Bytes.
Der Initialisierungsvektor ist für den Microsoft Base Cryptographic Provider standardmäßig auf 0 festgelegt. |
|
Legen Sie den Schlüsselwert für einen Des-Schlüssel (Data Encryption Standard ) fest. Der pbData-Parameter ist die Adresse eines Puffers, der den Schlüssel enthält. Dieser Puffer muss die gleiche Länge wie der Schlüssel aufweisen. Diese Eigenschaft gilt nur für DES-Schlüssel. |
|
Legen Sie den Auffüllmodus fest. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert, der einen numerischen Bezeichner empfängt, der die von der Verschlüsselung verwendete Auffüllmethode identifiziert. Dies kann einer der folgenden Werte sein.
|
|
pbData verweist auf einen DWORD-Wert , der den zu verwendenden Verschlüsselungsmodus angibt. Eine Liste der definierten Verschlüsselungsmodi finden Sie unter CryptGetKeyParam. Der Verschlüsselungsmodus ist für den Microsoft Base Cryptographic Provider standardmäßig auf CRYPT_MODE_CBC festgelegt. |
|
pbData zeigt auf einen DWORD-Wert , der die Anzahl der pro Zyklus verarbeiteten Bits angibt, wenn der Verschlüsselungsmodus " Ausgabefeedback " (OFB) oder "Cipher Feedback " (CFB) verwendet wird. Die Anzahl der pro Zyklus verarbeiteten Bits ist für den Microsoft Base Cryptographic Provider standardmäßig auf 8 festgelegt. |
Wenn im hKey-Parameter ein RSA-Schlüssel angegeben ist, kann der dwParam-Parameterwert der folgende Wert sein.
| Wert | Bedeutung |
|---|---|
|
Legen Sie die Parameter Optimal Asymmetric Encryption Padding (OAEP) (PKCS #1 Version 2) für den Schlüssel fest. Der pbData-Parameter ist die Adresse einer CRYPT_DATA_BLOB-Struktur , die die OAEP-Bezeichnung enthält. Diese Eigenschaft gilt nur für RSA-Schlüssel. |
Beachten Sie, dass die folgenden Werte nicht verwendet werden:
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
Ein Zeiger auf einen Puffer, der mit dem festzulegenden Wert initialisiert wird, bevor CryptSetKeyParam aufgerufen wird. Die Form dieser Daten variiert je nach Wert von dwParam.
[in] dwFlags
Wird nur verwendet, wenn dwParam KP_ALGID ist. Der dwFlags-Parameter wird verwendet, um Flagwerte für den aktivierten Schlüssel zu übergeben. Der dwFlags-Parameter kann Werte wie die Schlüsselgröße und die anderen Flagwerte enthalten, die beim Generieren desselben Schlüsseltyps mit CryptGenKey zulässig sind. Informationen zu zulässigen Flagwerten finden Sie unter CryptGenKey.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).
Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Die von "NTE" vorangestellten Fehlercodes werden von dem jeweiligen verwendeten CSP generiert. Es folgen einige mögliche Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Der CSP-Kontext wird derzeit von einem anderen Prozess verwendet. |
|
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 ungültiger Zeiger. |
|
Der dwFlags-Parameter ist ungleich null, oder der pbData-Puffer enthält einen ungültigen Wert. |
|
Der dwParam-Parameter gibt einen unbekannten Parameter an. |
|
Der CSP-Kontext, der beim Erstellen des hKey-Schlüssels angegeben wurde, kann nicht gefunden werden. |
|
Die Funktion ist auf unerwartete Weise fehlgeschlagen. |
|
Einige CSPs verfügen über hartcodierte P-, Q- und G-Werte. Wenn dies der Fall ist, verursacht die Verwendung von KP_P, KP_Q und KP_G für den Wert von dwParam diesen Fehler. |
Hinweise
Wenn die Parameter KP_Q, KP_P oder KP_X für einen PREGEN-Diffie-Hellman- oder DSS-Schlüssel festgelegt sind, müssen die Schlüssellängen mit der Schlüssellänge kompatibel sein, die mithilfe der oberen 16 Bits des dwFlags-Parameters festgelegt wurde, wenn der Schlüssel mit CryptGenKey erstellt wurde. Wenn in CryptGenKey keine Schlüssellänge festgelegt wurde, wurde die Standardschlüssellänge verwendet. Dies führt zu einem Fehler, wenn eine Schlüssellänge ohne Standard zum Festlegen von P, Q oder X verwendet wird.
Beispiele
Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Duplizieren eines Sitzungsschlüssels. Weitere Code, der diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Festlegen und Abrufen von Sitzungsschlüsselparametern .
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