CryptGetKeyParam-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 CryptGetKeyParam--Funktion ruft Daten ab, die die Vorgänge eines Schlüssels steuern. Wenn der Microsoft Cryptographic Service Provider verwendet wird, kann das basissymmetrische Schlüsselmaterial von dieser oder einer anderen Funktion nicht beschafft 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 Abfrage an, die erstellt wird.

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, sind die Algorithmusbezeichner, die zum Generieren des Schlüssels verwendet werden, vom verwendeten Anbieter abhängig. 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üsselchiffre ab. Der pbData--Parameter ist ein Zeiger auf einen DWORD- Wert, der die Blocklänge in Bits empfängt. Bei Datenstromchiffreist dieser Wert immer null. Wenn ein öffentliches/privates Schlüsselpaar durch hKey-angegeben wird, rufen Sie die Verschlüsselungs granularität des Schlüsselpaars ab. Der pbData--Parameter ist ein Zeiger auf einen DWORD- Wert, der die Verschlüsselungs granularität in Bits empfängt. Beispielsweise generiert der Microsoft Base Cryptographic Provider 512-Bit-RSA-Schlüsselpaare, sodass für diese Schlüssel ein Wert von 512 zurückgegeben wird. Wenn der Algorithmus für öffentliche Schlüssel Verschlüsselungnicht 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 Distinguished Encoding Rules (DER) codiert wurde. Der öffentliche Schlüssel, der im Zertifikat, muss mit der entsprechenden Signatur oder dem entsprechenden 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 können verwendet werden, um die Länge eines beliebigen Schlüsseltyps abzurufen. Microsoft kryptografische Dienstanbieter (CSPs) geben eine Schlüssellänge von 64 Bit für CALG_DES, 128 Bit für CALG_3DES_112und 192 Bit für CALG_3DESzurück. Diese Längen unterscheiden sich von den Längen, die zurückgegeben werden, wenn Sie Algorithmen mit dem dwParam- Wert der CryptGetProvParam--Funktion auf PP_ENUMALGSfestlegen. Die von diesem Aufruf zurückgegebene Länge ist die tatsächliche Größe des Schlüssels, einschließlich der im Schlüssel enthaltenen Paritätsbits. Microsoft-CSPs, die die CALG_CYLINK_MEKALG_ID unterstützen, geben 64 Bit für diesen Algorithmus zurück. CALG_CYLINK_MEK ist ein 40-Bit-Schlüssel, hat jedoch Parität und nullige Schlüsselbits, um die Schlüssellänge 64 Bit zu machen.
KP_SALT	Rufen Sie den Salzwert des Schlüssels ab. Der pbData--Parameter ist ein Zeiger auf ein BYTE- Array, das den Salzwert in form little-endian empfängt. Die Größe des Salzwerts variiert je nach verwendetem CSP und Algorithmus. Salzwerte gelten nicht für öffentlichen/privaten Schlüsselpaare.
KP_PERMISSIONS	Rufen Sie die Schlüsselberechtigungen ab. Der pbData--Parameter ist ein Zeiger auf einen DWORD- Wert, der die Berechtigungskennzeichnungen 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 Export während der Lebensdauer des Handles des Schlüssels zulassen. 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 werden kann. 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 Zulassen, dass Nachrichtenauthentifizierungscodes (MACs) mit Schlüssel verwendet werden. CRYPT_READ Zulassen, dass Werte gelesen werden. CRYPT_WRITE Festlegen von Werten zulassen.

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_P	Rufen Sie die Modulus-Primzahl P des DSS-Schlüssels ab. Der pbData--Parameter ist ein Zeiger auf einen Puffer, der den Wert in kleiner endischer Form empfängt. Der parameter pdwDataLen enthält die Größe des Puffers in Byte.
KP_Q	Rufen Sie die Modulus-Primzahl Q des DSS-Schlüssels ab. Der pbData--Parameter ist ein Zeiger auf einen Puffer, der den Wert in kleiner endischer Form empfängt. Der parameter pdwDataLen enthält die Größe des Puffers in Byte.
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 kleiner endischer Form empfängt. Der parameter pdwDataLen enthält die Größe des Puffers in Byte.

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	Rufen Sie 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 erhält.
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 Byte. Wenn die Blocklänge beispielsweise 64 Bit 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 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 Zufallszahlen. 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	Rufen Sie den Chiffremodusab. Der pbData--Parameter ist ein Zeiger auf einen DWORD- Wert, der einen Chiffremodusbezeichner empfängt. Weitere Informationen zu Verschlüsselungsmodi finden Sie unter Datenverschlüsselung und Entschlüsselung. Die folgenden Chiffremodusbezeichner sind derzeit definiert. CRYPT_MODE_CBC Der Chiffremodus ist Chiffreblockkette. CRYPT_MODE_CFB Der Chiffremodus ist Chiffrefeedback (CFB). Microsoft-CSPs unterstützen derzeit nur 8-Bit-Feedback im Verschlüsselungsfeedbackmodus. CRYPT_MODE_ECB Der Verschlüsselungsmodus ist elektronischen Codebook. CRYPT_MODE_OFB Der Verschlüsselungsmodus ist Ausgabefeedback (OFB). Microsoft-CSPs unterstützen derzeit den Ausgabefeedbackmodus nicht. CRYPT_MODE_CTS Der Verschlüsselungsmodus ist Chiffretext Diebstahlmodus.
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 Digital Signature Algorithm (DSA)-Schlüssel durch 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 null sind.
KP_KEYVAL	Dieser Wert wird nicht verwendet. Windows Vista, Windows Server 2003 und Windows XP: Abrufen des Werts des geheimen Vertrags aus einem importierten Diffie-Hellman Algorithmus Schlüssel vom Typ CALG_AGREEDKEY_ANY. Der pbData--Parameter ist die Adresse eines Puffers, der den Geheimvertragswert im little-endian-Format empfängt. Dieser Puffer muss dieselbe Länge wie der Schlüssel aufweisen. Der parameter dwFlags muss auf 0xF42A19B6 festgelegt werden. Diese Eigenschaft kann nur von einem Thread abgerufen werden, der unter dem lokalen Systemkonto ausgeführt wird. Diese Eigenschaft steht für die Verwendung in den oben aufgeführten Betriebssystemen zur Verfügung. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.

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 null sind.

KP_KEYVAL

Dieser Wert wird nicht verwendet.

Windows Vista, Windows Server 2003 und Windows XP: Abrufen des Werts des geheimen Vertrags aus einem importierten Diffie-Hellman Algorithmus Schlüssel vom Typ CALG_AGREEDKEY_ANY. Der pbData--Parameter ist die Adresse eines Puffers, der den Geheimvertragswert im little-endian-Format empfängt. Dieser Puffer muss dieselbe Länge wie der Schlüssel aufweisen. Der parameter dwFlags muss auf 0xF42A19B6 festgelegt werden. Diese Eigenschaft kann nur von einem Thread abgerufen werden, der unter dem lokalen Systemkonto ausgeführt wird. Diese Eigenschaft steht für die Verwendung in den oben aufgeführten Betriebssystemen zur Verfügung. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein.

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 null sind.

[out] pbData

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

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- auf Null verweist. Diese Funktion platziert die erforderliche Größe des Puffers in Byte im Wert, auf den pdwDataLenverweist. Weitere Informationen finden Sie unter Abrufen von Daten 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ückgegeben wird, 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 für die Eingabe angegeben ist. Bei eingaben 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, auf die dieser Parameter verweist, aktualisiert, 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 Null festgelegt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion "nonzero" zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

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

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 am häufigsten ein ungültiger Zeiger.
ERROR_MORE_DATA	Wenn der durch den parameter pbData 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 Byte in der Variablen, auf die von pdwDataLenverwiesen wird.
NTE_BAD_FLAGS	Der dwFlags Parameter ist nonzero.
NTE_BAD_KEY oder NTE_NO_KEY	Der vom 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
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

Siehe auch

CryptSetKeyParam-

Schlüsselgenerierung und Exchange-Funktionen

Freigeben über