CryptGetProvParam-Funktion (wincrypt.h)
Syntax
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parameter
[in] hProv
Ein Handle des CSP-Ziels der Abfrage. Dieses Handle muss mithilfe der CryptAcquireContext-Funktion erstellt worden sein.
[in] dwParam
Die Art der Abfrage. Die folgenden Abfragen werden definiert.
| Wert | Bedeutung |
|---|---|
|
Gibt die persönliche Identifikationsnummer (PIN) des Administrators im pbData-Parameter als LPSTR zurück. |
|
Diese Konstante wird nicht verwendet. |
|
Diese Konstante wird nicht verwendet. |
|
Gibt die Zertifikatkette zurück, die dem hProv-Handle zugeordnet ist. Die zurückgegebene Zertifikatkette ist X509_ASN_ENCODING codiert. |
|
Der Name des aktuellen Schlüsselcontainers als NULL-beendete CHAR-Zeichenfolge. Diese Zeichenfolge entspricht genau der Zeichenfolge, die im pszContainer-Parameter der CryptAcquireContext-Funktion übergeben wird, um den zu verwendenden Schlüsselcontainer anzugeben. Der parameter pszContainer kann gelesen werden, um den Namen des Standardschlüsselcontainers zu bestimmen. |
|
Nicht von Microsoft-CSPs implementiert. Dieses Verhalten kann von anderen CSPs implementiert werden.
Windows XP: Dieser Parameter wird nicht unterstützt. |
|
Eine PROV_ENUMALGS Struktur, die Informationen zu einem Algorithmus enthält, der vom abgefragten CSP unterstützt wird.
Wenn dieser Wert zum ersten Mal gelesen wird, muss der dwFlags-Parameter das flag CRYPT_FIRST enthalten. Dies bewirkt, dass diese Funktion das erste Element in der Enumeration abruft. Die nachfolgenden Elemente können dann abgerufen werden, indem Sie das CRYPT_NEXT-Flag im dwFlags-Parameter festlegen. Wenn diese Funktion mit dem ERROR_NO_MORE_ITEMS Fehlercode fehlschlägt, wurde das Ende der Enumeration erreicht. Diese Funktion ist nicht threadsicher, und alle verfügbaren Algorithmen werden möglicherweise nicht aufgelistet, wenn diese Funktion in einem Multithreadkontext verwendet wird. |
|
Eine PROV_ENUMALGS_EX-Struktur , die Informationen zu einem Algorithmus enthält, der vom abgefragten CSP unterstützt wird. Die zurückgegebene Struktur enthält mehr Informationen zum Algorithmus als die für PP_ENUMALGS zurückgegebene Struktur.
Wenn dieser Wert zum ersten Mal gelesen wird, muss der dwFlags-Parameter das flag CRYPT_FIRST enthalten. Dies bewirkt, dass diese Funktion das erste Element in der Enumeration abruft. Die nachfolgenden Elemente können dann abgerufen werden, indem Sie das CRYPT_NEXT-Flag im dwFlags-Parameter festlegen. Wenn diese Funktion mit dem ERROR_NO_MORE_ITEMS Fehlercode fehlschlägt, wurde das Ende der Enumeration erreicht. Diese Funktion ist nicht threadsicher, und alle verfügbaren Algorithmen werden möglicherweise nicht aufgelistet, wenn diese Funktion in einem Multithreadkontext verwendet wird. |
|
Der Name eines der Schlüsselcontainer, die vom CSP verwaltet werden, in Form einer CHAR-Zeichenfolge mit Null-Beendigung.
Wenn dieser Wert zum ersten Mal gelesen wird, muss der dwFlags-Parameter das flag CRYPT_FIRST enthalten. Dies bewirkt, dass diese Funktion das erste Element in der Enumeration abruft. Die nachfolgenden Elemente können dann abgerufen werden, indem Sie das CRYPT_NEXT-Flag im dwFlags-Parameter festlegen. Wenn diese Funktion mit dem ERROR_NO_MORE_ITEMS Fehlercode fehlschlägt, wurde das Ende der Enumeration erreicht. Zum Auflisten von Schlüsselcontainern, die einem Computer zugeordnet sind, rufen Sie zuerst CryptAcquireContext mit dem flag CRYPT_MACHINE_KEYSET auf, und verwenden Sie dann das von CryptAcquireContext zurückgegebene Handle als hProv-Parameter im Aufruf von CryptGetProvParam. Diese Funktion ist nicht threadsicher, und alle verfügbaren Algorithmen werden möglicherweise nicht aufgelistet, wenn diese Funktion in einem Multithreadkontext verwendet wird. |
|
Diese Konstante wird nicht verwendet. |
|
Gibt an, dass der aktuelle CSP das dwProtocols-Element der PROV_ENUMALGS_EX-Struktur unterstützt. Wenn diese Funktion erfolgreich ist, unterstützt der CSP das dwProtocols-Element der PROV_ENUMALGS_EX-Struktur . Wenn diese Funktion mit einem NTE_BAD_TYPE Fehlercode fehlschlägt, unterstützt der CSP den dwProtocols-Member nicht. |
|
Diese Konstante wird nicht verwendet. |
|
Ein DWORD-Wert , der angibt, wie der CSP implementiert wird. Eine Tabelle mit möglichen Werten finden Sie unter Hinweise. |
|
Diese Abfrage wird nicht verwendet. |
|
Gibt an, dass die Schlüsselaustausch-PIN in pbData enthalten ist. Die PIN wird als NULL-beendete ASCII-Zeichenfolge dargestellt. |
|
Ruft die Sicherheitsbeschreibung für den Schlüsselspeichercontainer ab. Der pbData-Parameter ist die Adresse einer SECURITY_DESCRIPTOR-Struktur , die den Sicherheitsdeskriptor für den Schlüsselspeichercontainer empfängt. Die Sicherheitsbeschreibung wird im selbstrelativen Format zurückgegeben. |
|
Bestimmt, ob der hProv-Parameter ein Computerschlüsselsatz ist. Der pbData-Parameter muss ein DWORD sein. DWORD wird auf das CRYPT_MACHINE_KEYSET-Flag festgelegt, wenn dieses Flag an die Funktion CryptAcquireContext übergeben wurde. |
|
Gibt Informationen zu den Schlüsselbezeichnerwerten zurück, die der CSP unterstützt. Schlüsselbezeichnerwerte werden in einem logischen OR verknüpft und im pbData-Parameter des Aufrufs als DWORD zurückgegeben. Beispielsweise gibt der Microsoft Base-Kryptografieanbieter Version 1.0 den DWORD-Wert AT_SIGNATURE | AT_KEYEXCHANGE. |
|
Gibt den DWORD-Wert CRYPT_SEC_DESCR zurück. |
|
Die Anzahl der Bits für die Inkrementlänge von AT_KEYEXCHANGE. Diese Informationen werden mit Informationen verwendet, die im PP_ENUMALGS_EX-Wert zurückgegeben werden. Mit den informationen, die bei Verwendung von PP_ENUMALGS_EX und PP_KEYX_KEYSIZE_INC zurückgegeben werden, können die gültigen Schlüssellängen für AT_KEYEXCHANGE bestimmt werden. Diese Schlüssellängen können dann mit CryptGenKey verwendet werden. Wenn ein CSP beispielsweise CALG_RSA_KEYX (AT_KEYEXCHANGE) mit einer Mindestschlüssellänge von 512 Bit und maximal 1024 Bit aufzählt und die Inkrementlänge als 64 Bit zurückgibt, sind gültige Schlüssellängen 512, 576, 640,... 1024. |
|
Der Name des CSP in Form einer CHAR-Zeichenfolge mit NULL-Beendigung. Diese Zeichenfolge ist identisch mit der, die im pszProvider-Parameter der CryptAcquireContext-Funktion übergeben wird, um anzugeben, dass der aktuelle CSP verwendet werden soll. |
|
Ein DWORD-Wert , der den Anbietertyp des CSP angibt. |
|
Ruft den Stammzertifikatspeicher für die intelligente Karte ab. Dieser Zertifikatspeicher enthält alle Stammzertifikate, die auf der intelligenten Karte gespeichert sind.
Der pbData-Parameter ist die Adresse einer HCERTSTORE-Variablen , die das Handle des Zertifikatspeichers empfängt. Wenn dieses Handle nicht mehr benötigt wird, muss es vom Aufrufer mithilfe der CertCloseStore-Funktion geschlossen werden. Windows Server 2003 und Windows XP: Dieser Parameter wird nicht unterstützt. |
|
Die Größe des Sitzungsschlüssels in Bits. |
|
Wird mit Servergated-Kryptografie verwendet. |
|
Die Anzahl der Bits für die Inkrementlänge von AT_SIGNATURE. Diese Informationen werden mit Informationen verwendet, die im PP_ENUMALGS_EX-Wert zurückgegeben werden. Mit den informationen, die bei Verwendung von PP_ENUMALGS_EX und PP_SIG_KEYSIZE_INC zurückgegeben werden, können die gültigen Schlüssellängen für AT_SIGNATURE bestimmt werden. Diese Schlüssellängen können dann mit CryptGenKey verwendet werden.
Wenn ein CSP beispielsweise CALG_RSA_SIGN (AT_SIGNATURE) mit einer Mindestschlüssellänge von 512 Bit und maximal 1024 Bit aufzählt und die inkrementale Länge als 64 Bit zurückgibt, sind gültige Schlüssellängen 512, 576, 640,... 1024. |
|
Gibt an, dass die Pin für die Schlüsselsignatur in pbData enthalten ist. Die PIN wird als ASCII-Zeichenfolge mit NULL-Beendigung dargestellt. |
|
Ruft den Bezeichner des intelligenten Karte ab. Der pbData-Parameter ist die Adresse einer GUID-Struktur, die den Bezeichner des intelligenten Karte empfängt.
Windows Server 2003 und Windows XP: Dieser Parameter wird nicht unterstützt. |
|
Ruft den Namen des intelligenten Karte-Readers ab. Der pbData-Parameter ist die Adresse eines ANSI-Zeichenarrays, das eine NULL-endende ANSI-Zeichenfolge empfängt, die den Namen des Smart Karte Reader enthält. Die Größe dieses Puffers, der in der Variablen enthalten ist, auf die der pdwDataLen-Parameter verweist, muss den NULL-Abschlusszeichen enthalten.
Windows Server 2003 und Windows XP: Dieser Parameter wird nicht unterstützt. |
|
Die Größe des symmetrischen Schlüssels. |
|
Diese Abfrage wird nicht verwendet. |
|
Der eindeutige Containername des aktuellen Schlüsselcontainers in Form einer CHAR-Zeichenfolge mit NULL-Beendigung. Für viele CSPs ist dieser Name der gleiche Name, der zurückgegeben wird, wenn der PP_CONTAINER Wert verwendet wird. Die CryptAcquireContext-Funktion muss mit diesem Containernamen funktionieren. |
|
Gibt an, ob ein Hardware-Zufallszahlengenerator (RNG) unterstützt wird. Wenn PP_USE_HARDWARE_RNG angegeben wird, ist die Funktion erfolgreich und gibt TRUE zurück, wenn ein Hardware-RNG unterstützt wird. Die Funktion schlägt fehl und gibt FALSE zurück, wenn ein Hardware-RNG nicht unterstützt wird. Wenn ein RNG unterstützt wird, kann PP_USE_HARDWARE_RNG in CryptSetProvParam festgelegt werden, um anzugeben, dass der CSP ausschließlich die Hardware-RNG für diesen Anbieterkontext verwenden muss. Wenn PP_USE_HARDWARE_RNG verwendet wird, muss der pbData-ParameterNULL und dwFlags null sein.
Keines der Microsoft-CSPs unterstützt derzeit die Verwendung eines Hardware-RNG. |
|
Ruft den Benutzerzertifikatspeicher für die intelligente Karte ab. Dieser Zertifikatspeicher enthält alle Benutzerzertifikate, die auf dem intelligenten Karte gespeichert sind. Die Zertifikate in diesem Speicher werden mithilfe von PKCS_7_ASN_ENCODING oder X509_ASN_ENCODING Codierung codiert und sollten die eigenschaft CERT_KEY_PROV_INFO_PROP_ID enthalten.
Der pbData-Parameter ist die Adresse einer HCERTSTORE-Variablen , die das Handle eines In-Memory-Zertifikatspeichers empfängt. Wenn dieses Handle nicht mehr benötigt wird, muss es vom Aufrufer mithilfe der CertCloseStore-Funktion geschlossen werden. Windows Server 2003 und Windows XP: Dieser Parameter wird nicht unterstützt. |
|
Die Versionsnummer des CSP. Das am wenigsten signifikante Byte enthält die Nebenversionsnummer und das nächstbeste Byte die Hauptversionsnummer. Version 2.0 wird als 0x00000200 dargestellt. Um die Abwärtskompatibilität mit früheren Versionen von Microsoft Base Cryptographic Provider und Microsoft Enhanced Cryptographic Provider zu gewährleisten, behalten die Anbieternamen in späteren Versionen die Bezeichnung "v1.0" bei. |
[out] pbData
Ein Zeiger auf einen Puffer zum Empfangen der Daten. Die Form dieser Daten variiert je nach Wert von dwParam. Wenn dwParam auf PP_USE_HARDWARE_RNG festgelegt ist, muss pbData auf NULL festgelegt werden.
Dieser Parameter kann NULL sein, um die Größe dieser Informationen für die Speicherbelegung festzulegen. Weitere Informationen finden Sie unter Abrufen von Daten mit unbekannter Länge.
[in, out] pdwDataLen
Ein Zeiger auf einen DWORD-Wert , der die Größe des Puffers in Bytes angibt, auf den der pbData-Parameter verweist. Wenn die Funktion zurückgibt, enthält der DWORD-Wert die Anzahl der im Puffer gespeicherten oder zu speichernden Bytes.
Wenn PP_ENUMALGS oder PP_ENUMALGS_EX festgelegt ist, funktioniert der pdwDataLen-Parameter etwas anders. Wenn pbDataNULL ist oder der Wert, auf den pdwDataLen verweist, zu klein ist, entspricht der in diesem Parameter zurückgegebene Wert der Größe des größten Elements in der Enumerationsliste und nicht der Größe des Elements, das gerade gelesen wird.
Wenn PP_ENUMCONTAINERS festgelegt ist, gibt der erste Aufruf der Funktion die Größe des vom aktuellen Anbieter maximal zulässigen Schlüsselcontainers zurück. Dies steht im Gegensatz zu anderen möglichen Verhaltensweisen, z. B. der Rückgabe der Länge des längsten vorhandenen Containers oder der Länge des aktuellen Containers. Nachfolgende Aufzählungsaufrufe ändern den dwLen-Parameter nicht. Für jeden enumerierten Container kann der Aufrufer die Länge der Zeichenfolge mit NULL-Termin programmgesteuert bestimmen, falls gewünscht. Wenn einer der Enumerationswerte gelesen wird und der pbData-ParameterNULL ist, muss das flag CRYPT_FIRST angegeben werden, damit die Größeninformationen ordnungsgemäß abgerufen werden.
[in] dwFlags
Wenn dwParamPP_KEYSET_SEC_DESCR ist, wird der Sicherheitsdeskriptor für den Schlüsselcontainer , in dem die Schlüssel gespeichert sind, abgerufen. In diesem Fall wird dwFlags verwendet, um die SECURITY_INFORMATION Bitflags zu übergeben, die die angeforderten Sicherheitsinformationen angeben, wie im Platform SDK definiert. SECURITY_INFORMATION Bitflags können mit einem bitweisen OR-Vorgang kombiniert werden.
Die folgenden Werte werden für die Verwendung mit PP_KEYSET_SEC_DESCR definiert.
Die folgenden Werte werden für die Verwendung mit PP_ENUMALGS, PP_ENUMALGS_EX und PP_ENUMCONTAINERS definiert.
| Wert | Bedeutung |
|---|---|
|
Rufen Sie das erste Element in der Enumeration ab. Dies hat die gleiche Auswirkung wie das Zurücksetzen des Enumerators. |
|
Rufen Sie das nächste Element in der Enumeration ab. Wenn keine weiteren Elemente abgerufen werden können, schlägt diese Funktion fehl, und der letzte Fehler wird auf ERROR_NO_MORE_ITEMS festgelegt. |
|
Abrufen von SGC-fähigen Zertifikaten (Server-Gated Cryptography ). SGC-fähige Zertifikate werden nicht mehr unterstützt. |
|
Dieses Flag wird nicht verwendet. |
|
Dieses Flag wird nicht verwendet. |
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 vom jeweiligen verwendeten CSP generiert. Es folgen einige mögliche Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
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. |
|
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 Byte in der Variablen, auf die pdwDataLen verweist. |
|
Das Ende der Enumerationsliste wurde erreicht. Es wurden keine gültigen Daten in den pbData-Puffer eingefügt. Dieser Fehlercode wird nur zurückgegeben, wenn dwParam gleich PP_ENUMALGS oder PP_ENUMCONTAINERS ist. |
|
Der dwFlags-Parameter gibt ein ungültiges Flag an. |
|
Der dwParam-Parameter gibt eine unbekannte Wertnummer an. |
|
Der von hProv angegebene CSP-Kontext ist ungültig. |
Hinweise
Diese Funktion darf nicht in einem Thread eines Multithreadprogramms verwendet werden.
Die folgenden Werte werden in pbData zurückgegeben, wenn dwParam PP_IMPTYPE ist.
| Wert | Bedeutung |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
Die Implementierung erfolgt in der Hardware. |
| CRYPT_IMPL_SOFTWARE 0x02 |
Die Implementierung erfolgt in Software. |
| CRYPT_IMPL_MIXED 0x03 |
Die Implementierung umfasst sowohl Hardware als auch Software. |
| CRYPT_IMPL_UNKNOWN 0x04 |
Der Implementierungstyp ist unbekannt. |
| CRYPT_IMPL_REMOVABLE 0x08 |
Die Implementierung erfolgt auf Wechselmedien. |
Der dwFlags-Parameter wird verwendet, um die SECURITY_INFORMATION Bitflags zu übergeben, die die angeforderten Sicherheitsinformationen angeben. Der Zeiger auf den Sicherheitsdeskriptor wird im pbData-Parameter zurückgegeben, und die Länge des Sicherheitsdeskriptors wird im pdwDataLen-Parameter zurückgegeben. Schlüsselcontainersicherheit wird mit SetFileSecurity und GetFileSecurity behandelt.
Die Klasse eines Algorithmus, der mit dwParam auf PP_ENUMALGS oder PP_ENUMALGS_EX festgelegt ist, kann bestimmt werden. Dies kann geschehen, um eine Liste der unterstützten Verschlüsselungsalgorithmen anzuzeigen und den Rest zu ignorieren. Das Makro GET_ALG_CLASS(x) verwendet einen Algorithmusbezeichner als Argument und gibt einen Code zurück, der die allgemeine Klasse dieses Algorithmus angibt. Mögliche Rückgabewerte sind:
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
In der folgenden Tabelle sind die vom Microsoft-Basis-Kryptografieanbieter unterstützten Algorithmen zusammen mit der Klasse der einzelnen Algorithmen aufgeführt.
| Name | Bezeichner | Klasse |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
Anwendungen dürfen keinen Algorithmus mit einem Algorithmusbezeichner verwenden, der nicht erkannt wird. Die Verwendung eines unbekannten kryptografischen Algorithmus kann zu unvorhersehbaren Ergebnissen führen.
Beispiele
Das folgende Beispiel zeigt die Suche nach dem Namen des CSP, der einem Kryptografiedienstanbieterhandle zugeordnet ist, und dem Namen des Schlüsselcontainers, der dem Handle zugeordnet ist. Den vollständigen Kontext für dieses Beispiel finden Sie unter Beispiel-C-Programm: Verwenden von CryptAcquireContext.
Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Auflisten von CSP-Anbietern und Anbietertypen.
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
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 |