CryptSetKeyParam-Funktion (wincrypt.h)

Artikel
07/16/2024

Wichtige Diese API ist veraltet. Neue und vorhandene Software sollten mit der Verwendung Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Versionen entfernen.

Die CryptSetKeyParam--Funktion passt verschiedene Aspekte der Vorgänge eines Sitzungsschlüssels an. Die von dieser Funktion festgelegten Werte bleiben nicht im Arbeitsspeicher erhalten und können nur in einer einzigen Sitzung verwendet werden.

Der Microsoft Base Cryptographic Provider erlaubt keine Einstellung von Werten für den Schlüsselaustausch oder Signaturschlüssel; 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
KP_ALGID	pbData- verweist auf eine entsprechende ALG_ID. Dies wird beim Austauschen von Sitzungsschlüsseln mit dem Microsoft Base Digital Signature Standard (DSS), Diffie-Hellman Kryptografieanbieter oder kompatiblen CSPs verwendet. Nachdem ein Schlüssel mit der CryptImportKey--Funktion vereinbart wurde, wird der Sitzungsschlüssel durch Festlegen des Algorithmustyps für die Verwendung aktiviert.
KP_CERTIFICATE	pbData- ist die Adresse eines Puffers, der das X.509-Zertifikat enthält, das mithilfe Distinguished Encoding Rules (DER) codiert wurde. Der öffentliche Schlüssel im Zertifikat muss mit der entsprechenden Signatur oder dem entsprechenden Exchange-Schlüssel übereinstimmen.
KP_PERMISSIONS	pbData- verweist auf einen DWORD- Wert, der null oder mehr Berechtigungskennzeichnungen angibt. Eine Beschreibung dieser Flags finden Sie unter CryptGetKeyParam.
KP_SALT	pbData- verweist auf ein BYTE- Array, das einen neuen Salzwert angibt, Teil des Sitzungsschlüssels sein soll. Die Größe des Salzwerts variiert je nach verwendeter CSP. Bestimmen Sie vor dem Festlegen dieses Werts die Größe des Salzwerts, indem Sie die CryptGetKeyParam--Funktion aufrufen. Salzwerte werden verwendet, um die Sitzungsschlüssel eindeutiger zu machen, wodurch Wörterbuchangriffe schwieriger werden. Der Salzwert ist standardmäßig null für den Microsoft Base-Kryptografieanbieter.
KP_SALT_EX	pbData- verweist auf eine CRYPT_INTEGER_BLOB Struktur, die das Salz enthält. Weitere Informationen finden Sie unter Angeben eines Salzwerts.

Wenn ein Digital Signature Standard (DSS)-Schlüssel durch den hKey--Parameter angegeben wird, kann der dwParam- Wert auch auf einen der folgenden Werte festgelegt werden.

Wert	Bedeutung
KP_G	pbData- verweist auf den Generator G aus dem DSS-Schlüssel-BLOB-. Die Daten befinden sich in Form einer CRYPT_INTEGER_BLOB Struktur, wobei das pbData-element der Wert ist, und das cbData--Element die Länge des Werts ist. Der Wert wird ohne Kopfzeileninformationen und in little-endian Form erwartet.
KP_P	pbData- verweist auf das Hauptmodul P eines DSS-Schlüssel-BLOB. Die Daten befinden sich in Form einer CRYPT_INTEGER_BLOB Struktur. Das pbData-element ist der Wert, und das cbData Member ist die Länge des Werts. Der Wert wird ohne Kopfzeileninformationen und in little-endian Form erwartet.
KP_Q	pbData- verweist auf das Haupt-Q eines DSS-Schlüssel-BLOB. Die Daten befinden sich in Form einer CRYPT_INTEGER_BLOB Struktur, in der das pbData-element der Wert ist, und das cbData Member die Länge des Werts ist. Der Wert wird ohne Kopfzeileninformationen und in little-endian Form erwartet.
KP_X	Nachdem die P-, Q- und G-Werte festgelegt wurden, kann ein Aufruf, der den KP_X Wert für dwParam- angibt, und NULL- für den pbData--Parameter an die CryptSetKeyParam--Funktion vorgenommen werden. Dadurch werden die X- und Y-Werte generiert.

Wenn ein Diffie-Hellman Algorithmus oder Digital Signature Algorithm (DSA)-Schlüssel durch hKey-angegeben wird, kann der dwParam- Wert auch auf einen der folgenden Werte festgelegt werden.

Wert	Bedeutung
KP_CMS_DH_KEY_INFO	Legt die Informationen für einen importierten Diffie-Hellman Schlüssel fest. Der parameter pbData ist die Adresse einer CMS_DH_KEY_INFO Struktur, die die festzulegenden Schlüsselinformationen enthält.
KP_PUB_PARAMS	Legt die öffentlichen Parameter (P, Q, G usw.) eines DSS oder Diffie-Hellman Schlüssels fest. Der Tastenziehpunkt 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, wobei 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. Nachdem dieser Aufruf erfolgt ist, sollte der KP_X Parameterwert mit CryptSetKeyParam- verwendet werden, um den tatsächlichen privaten Schlüssel zu erstellen. Der parameter KP_PUB_PARAMS wird anstelle mehrerer Aufrufe mit den Parameterwerten KP_P, KP_Q und KP_G verwendet.

Wert

Bedeutung

KP_CMS_DH_KEY_INFO

Legt die Informationen für einen importierten Diffie-Hellman Schlüssel fest. Der parameter pbData ist die Adresse einer CMS_DH_KEY_INFO Struktur, die die festzulegenden Schlüsselinformationen enthält.

KP_PUB_PARAMS

Legt die öffentlichen Parameter (P, Q, G usw.) eines DSS oder Diffie-Hellman Schlüssels fest. Der Tastenziehpunkt 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, wobei 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. Nachdem dieser Aufruf erfolgt ist, sollte der KP_X Parameterwert mit CryptSetKeyParam- verwendet werden, um den tatsächlichen privaten Schlüssel zu erstellen. Der parameter KP_PUB_PARAMS wird anstelle mehrerer Aufrufe mit den Parameterwerten KP_P, KP_Q und KP_G verwendet.

Wenn ein Blockchiffre Sitzungsschlüssel durch den hKey--Parameter angegeben wird, kann der dwParam- Wert auch auf einen der folgenden Werte festgelegt werden.

Wert	Bedeutung
KP_EFFECTIVE_KEYLEN	Dieser Werttyp kann nur mit RC2-Schlüsseln verwendet werden und wurde aufgrund der Implementierung der CryptSetKeyParam--Funktion im Microsoft Enhanced Cryptographic Provider vor Windows 2000 hinzugefügt. In der vorherigen Implementierung waren die RC2-Schlüssel im erweiterten Anbieter 128 Bit stärke, aber die effektive Schlüssellänge, die zum Erweitern von Schlüsseln in die Schlüsseltabelle verwendet wurde, war nur 40 Bit. Dadurch wurde die Stärke des Algorithmus auf 40 Bit reduziert. Um die Abwärtskompatibilität aufrechtzuerhalten, bleibt die vorherige Implementierung wie bisher erhalten. Die effektive Schlüssellänge kann jedoch auf mehr als 40 Bit festgelegt werden, indem KP_EFFECTIVE_KEYLEN im CryptSetKeyParam Aufruf verwendet wird. 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 eins, und das Maximum beträgt 40. Im Erweiterten Kryptografieanbieter von Microsoft beträgt der Mindestwert 1.024. Die Schlüssellänge muss vor dem Verschlüsseln oder Entschlüsseln mit dem Schlüssel festgelegt werden.
KP_HIGHEST_VERSION	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.
KP_IV	pbData- verweist auf ein BYTE- Array, das den Initialisierungsvektor angibt. Dieses Array muss BlockLength-/8-Elemente enthalten. Wenn die Blocklänge beispielsweise 64 Bit beträgt, besteht der Initialisierungsvektor aus 8 Bytes. Der Initialisierungsvektor ist standardmäßig für den Microsoft Base-Kryptografieanbieter auf Null festgelegt.
KP_KEYVAL	Legen Sie den Schlüsselwert für einen Data Encryption Standard (DES)-Schlüssel fest. Der pbData--Parameter ist die Adresse eines Puffers, der den Schlüssel enthält. Dieser Puffer muss dieselbe Länge wie der Schlüssel aufweisen. Diese Eigenschaft gilt nur für DES-Schlüssel.
KP_PADDING	Legen Sie den Abstandsmodus fest. Der pbData--Parameter ist ein Zeiger auf einen DWORD- Wert, der einen numerischen Bezeichner empfängt, der die Abstand Methode identifiziert, die von der Chiffreverwendet wird. Dies kann einer der folgenden Werte sein: PKCS5_PADDING Gibt die PKCS 5 -Abstandsmethode (Sek. 6.2) an. RANDOM_PADDING Der Abstand verwendet eine Zufallszahl. Diese Abstandsmethode wird von den von Microsoft bereitgestellten CSPs nicht unterstützt. ZERO_PADDING Der Abstand verwendet Nullen. Diese Abstandsmethode wird von den von Microsoft bereitgestellten CSPs nicht unterstützt.
KP_MODE	pbData- verweist auf einen DWORD- Wert, der den zu verwendenden Verschlüsselungs modus angibt. Eine Liste der definierten Chiffremodi finden Sie unter CryptGetKeyParam. Der Verschlüsselungsmodus ist standardmäßig für den Microsoft Base-Kryptografieanbieter auf CRYPT_MODE_CBC festgelegt.
KP_MODE_BITS	pbData- verweist auf einen DWORD- Wert, der die Anzahl der pro Zyklus verarbeiteten Bits angibt, wenn die Ausgabefeedback- (OFB) oder Chiffrefeedback- (CFB)-Verschlüsselungsmodus verwendet wird. Die Anzahl der pro Zyklus verarbeiteten Bits ist für den Microsoft Base-Kryptografieanbieter standardmäßig auf 8 festgelegt.

Wenn ein RSA--Schlüssel im hKey--Parameter angegeben wird, kann der dwParam Parameterwert der folgende Wert sein.

Wert	Bedeutung
KP_OAEP_PARAMS	Legen Sie die Parameter für den optimalen asymmetrischen Verschlüsselungsabstand (OAEP) (PKCS #1 Version 2) für den Schlüssel fest. Der parameter pbData 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 dem Wert 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 CryptGenKeyzulä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 null (FALSE). Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Die von "NTE" vorangestellten Fehlercodes werden vom verwendeten CSP generiert. Einige mögliche Fehlercodes folgen.

Rückgabecode	Beschreibung
ERROR_BUSY	Der CSP-Kontext wird derzeit von einem anderen Prozessverwendet.
ERROR_INVALID_HANDLE	Einer der Parameter gibt ein ungültiges Handle an.
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger.
NTE_BAD_FLAGS	Der dwFlags--Parameter ist "nonzero", oder der pbData- Puffer enthält einen ungültigen Wert.
NTE_BAD_TYPE	Der parameter dwParam gibt einen unbekannten Parameter an.
NTE_BAD_UID	Der CSP-Kontext, der beim Erstellen des hKey--Schlüssels angegeben wurde, wurde nicht gefunden.
NTE_FAIL	Die Funktion konnte auf unerwartete Weise nicht ausgeführt werden.
NTE_FIXEDPARAMETER	Einige CSPs weisen hartcodierte P-, Q- und G-Werte auf. Wenn dies der Fall ist, führt die Verwendung von KP_P, KP_Q und KP_G für den Wert von dwParam diesen Fehler aus.

Bemerkungen

Wenn die Parameter KP_Q, KP_P oder KP_X auf einem PREGEN-Diffie-Hellman- oder DSS-Schlüssel festgelegt werden, müssen die Schlüssellängen mit der Schlüssellänge kompatibel sein, mit den oberen 16 Bits des dwFlags Parameter festgelegt werden, wenn der Schlüssel mit CryptGenKeyerstellt wurde. Wenn in CryptGenKeykeine Schlüssellänge festgelegt wurde, wurde die Standardschlüssellänge verwendet. Dadurch wird ein Fehler erzeugt, wenn eine nicht standardmäßige Schlüssellänge verwendet wird, um P, Q oder X festzulegen.

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