CryptGetKeyParam-Funktion (wincrypt.h)

Artikel
03/03/2024

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

Die CryptGetKeyParam-Funktion ruft Daten ab, die die Vorgänge eines Schlüssels steuern. Wenn der Microsoft Cryptographic Service Provider verwendet wird, kann das Basismaterial für symmetrische Schlüssel nicht von dieser oder einer anderen Funktion abgerufen werden.

Syntax

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Parameter

[in] hKey

Das Handle des abgefragten Schlüssels.

[in] dwParam

Gibt den Typ der durchgeführten Abfrage an.

Für alle Schlüsseltypen kann dieser Parameter einen der folgenden Werte enthalten.

Wert	Bedeutung
KP_ALGID	Rufen Sie den Schlüsselalgorithmus ab. Der pbData-Parameter ist ein Zeiger auf einen ALG_ID Wert, der den Bezeichner des Algorithmus empfängt, der beim Erstellen des Schlüssels angegeben wurde. Wenn AT_KEYEXCHANGE oder AT_SIGNATURE für den Algid-Parameter der CryptGenKey-Funktion angegeben wird, hängen die Algorithmusbezeichner, die zum Generieren des Schlüssels verwendet werden, vom verwendeten Anbieter ab. Weitere Informationen finden Sie unter ALG_ID.
KP_BLOCKLEN	Wenn ein Sitzungsschlüssel durch den hKey-Parameter angegeben wird, rufen Sie die Blocklänge der Schlüsselverschlüsselung ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die Blocklänge in Bits empfängt. Bei Streamchiffren ist dieser Wert immer null. Wenn ein öffentliches/privates Schlüsselpaar von hKey angegeben wird, rufen Sie die Verschlüsselungsgranularität des Schlüsselpaars ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die Verschlüsselungsgranularität in Bits empfängt. Beispielsweise generiert der Microsoft Base Cryptographic Provider 512-Bit-RSA-Schlüsselpaare, sodass für diese Schlüssel der Wert 512 zurückgegeben wird. Wenn der Algorithmus für öffentliche Schlüssel keine Verschlüsselung unterstützt, ist der abgerufene Wert nicht definiert.
KP_CERTIFICATE	pbData ist die Adresse eines Puffers, der das X.509-Zertifikat empfängt, das mithilfe von Distinguished Encoding Rules (DER) codiert wurde. Der öffentliche Schlüssel im Zertifikat muss mit der entsprechenden Signatur oder dem Austauschschlüssel übereinstimmen.
KP_GET_USE_COUNT	Dieser Wert wird nicht verwendet.
KP_KEYLEN	Ruft die tatsächliche Länge des Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die Schlüssellänge in Bits empfängt. KP_KEYLEN kann verwendet werden, um die Länge eines beliebigen Schlüsseltyps abzurufen. Microsoft Cryptographic Service Provider (CSPs) geben eine Schlüssellänge von 64 Bit für CALG_DES, 128 Bit für CALG_3DES_112 und 192 Bit für CALG_3DES zurück. Diese Längen unterscheiden sich von den Längen, die zurückgegeben werden, wenn Sie Algorithmen aufzählen, deren dwParam-Wert der CryptGetProvParam-Funktion auf PP_ENUMALGS festgelegt ist. Die von diesem Aufruf zurückgegebene Länge entspricht der tatsächlichen Größe des Schlüssels, einschließlich der im Schlüssel enthaltenen Paritätsbits. Microsoft-CSPs, die die CALG_CYLINK_MEK unterstützen, geben ALG_ID 64 Bits für diesen Algorithmus zurück. CALG_CYLINK_MEK ist ein 40-Bit-Schlüssel, verfügt aber über Paritäts- und Nullschlüsselbits, um die Schlüssellänge auf 64 Bit zu machen.
KP_SALT	Rufen Sie den Salt-Wert des Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf ein BYTE-Array , das den Salt-Wert in Little-Endian-Form empfängt. Die Größe des Salzwerts variiert je nach verwendetem CSP und Algorithmus. Salt-Werte gelten nicht für Paare mit öffentlichem/privatem Schlüssel.
KP_PERMISSIONS	Rufen Sie die Schlüsselberechtigungen ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die Berechtigungsflags für den Schlüssel empfängt. Die folgenden Berechtigungsbezeichner sind derzeit definiert. Die Schlüsselberechtigungen können null oder eine Kombination aus einem oder mehreren der folgenden Werte sein. CRYPT_ARCHIVE Lassen Sie den Export während der Lebensdauer des Handles des Schlüssels zu. Diese Berechtigung kann nur festgelegt werden, wenn sie bereits im internen Berechtigungsfeld des Schlüssels festgelegt ist. Versuche, diese Berechtigung zu löschen, werden ignoriert. CRYPT_DECRYPT Entschlüsselung zulassen. CRYPT_ENCRYPT Verschlüsselung zulassen. CRYPT_EXPORT Zulassen, dass der Schlüssel exportiert wird. CRYPT_EXPORT_KEY Zulassen, dass der Schlüssel zum Exportieren von Schlüsseln verwendet wird. CRYPT_IMPORT_KEY Zulassen, dass der Schlüssel zum Importieren von Schlüsseln verwendet wird. CRYPT_MAC Lassen Sie die Verwendung von Nachrichtenauthentifizierungscodes (Message Authentication Codes , MACs) mit dem Schlüssel zu. CRYPT_READ Zulassen, dass Werte gelesen werden. CRYPT_WRITE Zulassen, dass Werte festgelegt werden.

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
KP_P	Rufen Sie die Modulusprimzahl P des DSS-Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf einen Puffer, der den Wert in little-endian-Form empfängt. Der pdwDataLen-Parameter enthält die Größe des Puffers in Bytes.
KP_Q	Rufen Sie die Modulusprimzahl Q des DSS-Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf einen Puffer, der den Wert in little-endian-Form empfängt. Der pdwDataLen-Parameter enthält die Größe des Puffers in Bytes.
KP_G	Rufen Sie den Generator G des DSS-Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf einen Puffer, der den Wert in little-endian-Form empfängt. Der pdwDataLen-Parameter enthält die Größe des Puffers in Bytes.

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

Wert	Bedeutung
KP_EFFECTIVE_KEYLEN	Ruft die effektive Schlüssellänge eines RC2-Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die effektive Schlüssellänge empfängt.
KP_IV	Rufen Sie den Initialisierungsvektor des Schlüssels ab. Der pbData-Parameter ist ein Zeiger auf ein BYTE-Array , das den Initialisierungsvektor empfängt. Die Größe dieses Arrays ist die Blockgröße in Bytes. Wenn die Blocklänge beispielsweise 64 Bits beträgt, besteht der Initialisierungsvektor aus 8 Bytes.
KP_PADDING	Rufen Sie den Abstandsmodus ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert, der einen numerischen Bezeichner empfängt, der die von der Verschlüsselung verwendete Abstandsmethode identifiziert. Dies kann einer der folgenden Werte sein. PKCS5_PADDING Gibt die PKCS 5-Auffüllungsmethode (Sek. 6.2) an. RANDOM_PADDING Die Auffüllung verwendet Zufallszahlen. Diese Auffüllungsmethode wird von den von Microsoft bereitgestellten CSPs nicht unterstützt. ZERO_PADDING Der Abstand verwendet Nullen. Diese Auffüllungsmethode wird von den von Microsoft bereitgestellten CSPs nicht unterstützt.
KP_MODE	Rufen Sie den Verschlüsselungsmodus ab. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der einen Verschlüsselungsmodusbezeichner empfängt. Weitere Informationen zu Verschlüsselungsmodi finden Sie unter Datenverschlüsselung und -entschlüsselung. Die folgenden Verschlüsselungsmodusbezeichner sind derzeit definiert. CRYPT_MODE_CBC Der Verschlüsselungsmodus ist die Verschlüsselungsblockkette. CRYPT_MODE_CFB Der Verschlüsselungsmodus ist Cipher Feedback (CFB). Microsoft CSPs unterstützen derzeit nur 8-Bit-Feedback im Verschlüsselungsfeedbackmodus. CRYPT_MODE_ECB Der Verschlüsselungsmodus ist ein elektronisches Codebook. CRYPT_MODE_OFB Der Verschlüsselungsmodus ist Output Feedback (OFB). Microsoft CSPs unterstützen derzeit den Ausgabefeedbackmodus nicht. CRYPT_MODE_CTS Der Verschlüsselungsmodus ist der Verschlüsselungstext-Stealing-Modus .
KP_MODE_BITS	Rufen Sie die Anzahl der Bits ab, die zurückgeführt werden sollen. Der pbData-Parameter ist ein Zeiger auf einen DWORD-Wert , der die Anzahl der Bits empfängt, die pro Zyklus verarbeitet werden, wenn die Ofb- oder CFB-Verschlüsselungsmodi verwendet werden.

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

Wert	Bedeutung
KP_VERIFY_PARAMS	Überprüft die Parameter eines Diffie-Hellman-Algorithmus oder DSA-Schlüssels. Der pbData-Parameter wird nicht verwendet, und der Wert, auf den pdwDataLen verweist, empfängt null. Diese Funktion gibt einen Wert ungleich Null zurück, wenn die Schlüsselparameter gültig oder andernfalls null sind.
KP_KEYVAL	Dieser Wert wird nicht verwendet. Windows Vista, Windows Server 2003 und Windows XP: Rufen Sie den Wert für die Geheimnisvereinbarung aus einem importierten Diffie-Hellman-Algorithmusschlüssel vom Typ CALG_AGREEDKEY_ANY ab. Der pbData-Parameter ist die Adresse eines Puffers, der den Wert der Geheimnisvereinbarung im Little-Endian-Format empfängt. Dieser Puffer muss die gleiche Länge wie der Schlüssel haben. Der dwFlags-Parameter muss auf 0xF42A19B6 festgelegt werden. Diese Eigenschaft kann nur von einem Thread abgerufen werden, der unter dem lokalen Systemkonto ausgeführt wird. Diese Eigenschaft ist für die Verwendung in den oben aufgeführten Betriebssystemen verfügbar. Es kann in nachfolgenden Versionen geändert oder entfernt werden.

Wert

Bedeutung

KP_VERIFY_PARAMS

Überprüft die Parameter eines Diffie-Hellman-Algorithmus oder DSA-Schlüssels. Der pbData-Parameter wird nicht verwendet, und der Wert, auf den pdwDataLen verweist, empfängt null.

Diese Funktion gibt einen Wert ungleich Null zurück, wenn die Schlüsselparameter gültig oder andernfalls null sind.

KP_KEYVAL

Dieser Wert wird nicht verwendet.

Windows Vista, Windows Server 2003 und Windows XP: Rufen Sie den Wert für die Geheimnisvereinbarung aus einem importierten Diffie-Hellman-Algorithmusschlüssel vom Typ CALG_AGREEDKEY_ANY ab. Der pbData-Parameter ist die Adresse eines Puffers, der den Wert der Geheimnisvereinbarung im Little-Endian-Format empfängt. Dieser Puffer muss die gleiche Länge wie der Schlüssel haben. Der dwFlags-Parameter muss auf 0xF42A19B6 festgelegt werden. Diese Eigenschaft kann nur von einem Thread abgerufen werden, der unter dem lokalen Systemkonto ausgeführt wird. Diese Eigenschaft ist für die Verwendung in den oben aufgeführten Betriebssystemen verfügbar. Es kann in nachfolgenden Versionen geändert oder entfernt werden.

Wenn ein Zertifikat durch hKey angegeben wird, kann der dwParam-Wert auch auf den folgenden Wert festgelegt werden.

Wert	Bedeutung
KP_CERTIFICATE	Ein Puffer, der das DER-codierte X.509-Zertifikat enthält. Der pbData-Parameter wird nicht verwendet, und der Wert, auf den pdwDataLen verweist, empfängt null. Diese Funktion gibt einen Wert ungleich Null zurück, wenn die Schlüsselparameter gültig oder andernfalls null sind.

[out] pbData

Ein Zeiger auf einen Puffer, der die Daten empfängt. Die Form dieser Daten hängt vom Wert von dwParam ab.

Wenn die Größe dieses Puffers nicht bekannt ist, kann die erforderliche Größe zur Laufzeit abgerufen werden, indem NULL für diesen Parameter übergeben und der Wert festgelegt wird, auf den pdwDataLen verweist, auf Null. Diese Funktion platziert die erforderliche Größe des Puffers in Bytes in den Wert, auf den pdwDataLen verweist. Weitere Informationen finden Sie unter Abrufen von Daten mit unbekannter Länge.

[in, out] pdwDataLen

Ein Zeiger auf einen DWORD-Wert , der beim Eintrag die Größe des Puffers in Bytes enthält, auf den der pbData-Parameter verweist. Wenn die Funktion zurückgibt, enthält der DWORD-Wert die Anzahl der im Puffer gespeicherten Bytes.

Hinweis Bei der Verarbeitung der im Puffer zurückgegebenen Daten müssen Anwendungen die tatsächliche Größe der zurückgegebenen Daten verwenden. Die tatsächliche Größe kann etwas kleiner sein als die Größe des Puffers, der bei der Eingabe angegeben wurde. Bei der Eingabe werden Puffergrößen manchmal groß genug angegeben, um sicherzustellen, dass die größtmöglichen Ausgabedaten in den Puffer passen. Bei der Ausgabe wird die Variable aktualisiert, auf die dieser Parameter verweist, um die tatsächliche Größe der in den Puffer kopierten Daten widerzuspiegeln.

[in] dwFlags

Dieser Parameter ist für die zukünftige Verwendung reserviert und muss auf 0 (null) festgelegt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Die von "NTE" vorangestellten Fehlercodes werden von dem jeweiligen verwendeten CSP generiert. Einige mögliche Fehlercodes sind die folgenden:

Rückgabecode	Beschreibung
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 in den meisten Fällen ein ungültiger Zeiger.
ERROR_MORE_DATA	Wenn der vom pbData-Parameter angegebene Puffer nicht groß genug ist, um die zurückgegebenen Daten aufzunehmen, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Bytes in der Variablen, auf die pdwDataLen verweist.
NTE_BAD_FLAGS	Der dwFlags-Parameter ist ungleich null.
NTE_BAD_KEY oder NTE_NO_KEY	Der durch den hKey-Parameter angegebene Schlüssel ist ungültig.
NTE_BAD_TYPE	Der dwParam-Parameter gibt eine unbekannte Wertnummer an.
NTE_BAD_UID	Der CSP-Kontext , der beim Erstellen des Schlüssels angegeben wurde, kann nicht gefunden werden.

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

CryptSetKeyParam

Schlüsselgenerierung und Exchange-Funktionen