PFXImportCertStore-Funktion (wincrypt.h)

  • Artikel

Die PFXImportCertStore-Funktion importiert ein PFX-BLOB und gibt das Handle eines Speichers zurück, der Zertifikate und alle zugeordneten privaten Schlüssel enthält.

Syntax

HCERTSTORE PFXImportCertStore(
  [in] CRYPT_DATA_BLOB *pPFX,
  [in] LPCWSTR         szPassword,
  [in] DWORD           dwFlags
);

Parameter

[in] pPFX

Ein Zeiger auf eine CRYPT_DATA_BLOB Struktur, die ein PFX-Paket mit den exportierten und verschlüsselten Zertifikaten und Schlüsseln enthält.

[in] szPassword

Ein Zeichenfolgenkennwort, das zum Entschlüsseln und Überprüfen des PFX-Pakets verwendet wird. Unabhängig davon, ob auf eine Zeichenfolge mit der Länge größer als 0 (null) oder auf eine leere Zeichenfolge oder auf NULL festgelegt ist, muss dieser Wert genau dem Wert entsprechen, der zum Verschlüsseln des Pakets verwendet wurde.

Wenn das PFX-Paket ab Windows 8 und Windows Server 2012 in der PFXExportCertStoreEx-Funktion mithilfe des PKCS12_PROTECT_TO_DOMAIN_SIDS-Flags erstellt wurde, versucht die FUNKTION PFXImportCertStore, das Kennwort mithilfe des Active Directory-Prinzipals (AD) zu entschlüsseln, der zum Verschlüsseln verwendet wurde. Der AD-Prinzipal wird im pvPara-Parameter angegeben. Wenn der szPassword-Parameter in der PFXExportCertStoreEx-Funktion eine leere Zeichenfolge oder NULL war und der dwFlags-Parameter auf PKCS12_PROTECT_TO_DOMAIN_SIDS festgelegt wurde, generierte diese Funktion zufällig ein Kennwort und verschlüsselte es mit dem im pvPara-Parameter angegebenen AD-Prinzipal . In diesem Fall sollten Sie das Kennwort auf den Wert (leere Zeichenfolge oder NULL) festlegen, der beim Erstellen des PFX-Pakets verwendet wurde. Die PFXImportCertStore-Funktion verwendet den AD-Prinzipal, um das zufällige Kennwort zu entschlüsseln, und das zufällig generierte Kennwort wird zum Entschlüsseln des PFX-Zertifikats verwendet.

Wenn Sie die Verwendung des Kennworts abgeschlossen haben, löschen Sie es aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen. Weitere Informationen zum Schützen von Kennwörtern finden Sie unter Behandeln von Kennwörtern.

[in] dwFlags

Der dwFlags-Parameter kann einer der folgenden Werte sein:

Wert Bedeutung
CRYPT_EXPORTABLE
0x00000001
 Importierte Schlüssel werden als exportierbar markiert. Wenn dieses Flag nicht verwendet wird, schlagen Aufrufe der CryptExportKey-Funktion mit dem Schlüsselhandle fehl.
CRYPT_USER_PROTECTED
0x00000002
 Der Benutzer muss über ein Dialogfeld oder eine andere Methode benachrichtigt werden, wenn bestimmte Versuche unternommen werden, diesen Schlüssel zu verwenden. Das genaue Verhalten wird vom verwendeten Kryptografiedienstanbieter (CSP ) angegeben.

Vor Internet Explorer 4.0 haben Die Kryptografiedienstanbieter von Microsoft dieses Flag ignoriert. Ab Internet Explorer 4.0 unterstützen Microsoft-Anbieter dieses Flag.

Wenn der Anbieterkontext mit festgelegtem CRYPT_SILENT-Flag geöffnet wurde, verursacht die Verwendung dieses Flags einen Fehler, und der letzte Fehler wird auf NTE_SILENT_CONTEXT festgelegt.
CRYPT_MACHINE_KEYSET
0x00000020
 Die privaten Schlüssel werden auf dem lokalen Computer und nicht unter dem aktuellen Benutzer gespeichert.
CRYPT_USER_KEYSET
0x00001000
 Die privaten Schlüssel werden unter dem aktuellen Benutzer und nicht auf dem lokalen Computer gespeichert, auch wenn das PFX-BLOB angibt, dass sie auf den lokalen Computer übertragen werden sollen.
PKCS12_PREFER_CNG_KSP
0x00000100
 Gibt an, dass der CNG-Schlüsselspeicheranbieter (KSP) bevorzugt wird. Wenn der CSP in der PFX-Datei angegeben ist, wird der CSP verwendet, andernfalls wird der KSP bevorzugt. Wenn der CNG-KSP nicht verfügbar ist, schlägt die PFXImportCertStore-Funktion fehl.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 Gibt an, dass der CNG-KSP immer verwendet wird. Wenn angegeben, versucht PFXImportCertStore , den CNG-KSP unabhängig von den Anbieterinformationen in der PFX-Datei zu verwenden. Wenn der CNG-KSP nicht verfügbar ist, schlägt der Import nicht fehl.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 Überschreiben des vorhandenen Schlüssels zulassen. Geben Sie dieses Flag an, wenn ein Szenario auftritt, in dem Sie eine PFX-Datei importieren müssen, die einen bereits vorhandenen Schlüsselnamen enthält. Wenn Sie beispielsweise eine PFX-Datei importieren, ist es möglich, dass bereits ein Container mit demselben Namen vorhanden ist, da kein eindeutiger Namespace für Schlüsselcontainer vorhanden ist. Wenn Sie einen "TestKey" auf Ihrem Computer erstellt haben und dann eine PFX-Datei importieren, die auch "TestKey" als Schlüsselcontainer enthält, ermöglicht die einstellung PKCS12_ALLOW_OVERWRITE_KEY das Überschreiben des Schlüssels.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PKCS12_NO_PERSIST_KEY
0x00008000
 Speichern Sie den Schlüssel nicht. Geben Sie dieses Flag an, wenn Sie den Schlüssel nicht beibehalten möchten. Wenn es beispielsweise nicht erforderlich ist, den Schlüssel nach der Überprüfung zu speichern, können Sie dieses Flag angeben, um den Schlüssel sofort zu verwerfen, anstatt einen Container zu erstellen und ihn dann zu löschen.
Hinweis Wenn das PKCS12_NO_PERSIST_KEY-Flag *nicht* festgelegt ist, werden Schlüssel auf dem Datenträger beibehalten. Wenn Sie die Schlüssel nicht über ihre Verwendung hinaus beibehalten möchten, müssen Sie sie löschen, indem Sie die CryptAcquireContext-Funktion mit dem imdwFlags-Parameter festgelegten CRYPT_DELETEKEYSET-Flag aufrufen.
Hinweis Weitere Überlegungen:

  • Bei Verwendung von PKCS12_NO_PERSIST_KEY wird die eigenschaft CERT_KEY_CONTEXT_PROP_ID intern für das Zertifikat festgelegt, und CERT_KEY_CONTEXT_PROP_ID enthält die NCRYPT_KEY_HANDLE.

  • Wenn die PKCS12_NO_PERSIST_KEY nicht verwendet wird, wird die eigenschaft CERT_KEY_PROV_INFO_PROP_ID festgelegt.

  • Wenn das Zertifikat mit dem nicht persistenten Schlüssel an einen anderen Prozess gemarshallt wird, wird die eigenschaft CERT_KEY_CONTEXT_PROP_ID nicht marshalled.

  • Damit NO_PERSIST funktioniert, muss es sich im selben Prozess befinden , und der Benutzer des PCCERT_CONTEXT muss die CERT_KEY_CONTEXT_PROP_ID unterstützen. Dies gilt in der Regel während eines TLS-Handshakes: Wenn der Handshake außerhalb des aufrufenden Prozesses in LSASS.exe ausgeführt wird, ist es nicht möglich, PKCS12_NO_PERSIST_KEY beim Wechsel vom aufrufenden Prozess zu LSASS zu verwenden (da der NCRYPT_KEY_HANDLE ein Zeiger auf eine Datenstruktur und kein Kernelhandle ist).

 
Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Importieren Sie alle erweiterten Eigenschaften für das Zertifikat, die beim Exportieren im Zertifikat gespeichert wurden.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
0x10000000
 Entpacken Sie die Ergebnisse, aber nicht beibehalten.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ein Handle an einen Zertifikatspeicher zurück, der die importierten Zertifikate enthält, einschließlich verfügbarer privater Schlüssel.

Wenn die Funktion fehlschlägt, d. h., wenn der Parameter password keine genaue Übereinstimmung mit dem Kennwort enthält, das zum Verschlüsseln des exportierten Pakets verwendet wurde, oder wenn andere Probleme beim Decodieren des PFX-BLOBs aufgetreten sind, gibt die Funktion NULL zurück, und ein Fehlercode kann durch Aufrufen der GetLastError-Funktion gefunden werden.

Hinweise

Die PFXImportCertStore-Funktion öffnet einen temporären Speicher. Wenn die Funktion erfolgreich ist, sollten Sie das Handle für den Speicher schließen, indem Sie die CertCloseStore-Funktion aufrufen.

Wenn Sie ein Zertifikat aus dem PFX-Paket importieren, Der CSP/KSP-Containername wird mithilfe der AttributeId mit OID 1.3.6.1.4.1.311.17.1 des PKCS8ShroudedKeyBag SafeBag [bagId: 1.2.840.113549.1.1.12.10.1.2( Ausführliche Informationen zur ASN.1-Struktur finden Sie unter PKCS #12 ).

  • AttributeId: 1.3.6.1.4.1.311.17.1
  • Wert: Der KSP-Name oder CSP-Name

Wenn die AttributeId nicht vorhanden ist und das PREFER_CNG-Flag übergeben wird, wird MS_KEY_STORAGE_PROVIDER ausgewählt. Wenn die AttributeId nicht vorhanden ist und das flag PREFER_CNG nicht übergeben wird, wird der Anbietername basierend auf dem Public Key-Algorithmus bestimmt (d. a. der Algorithmus für öffentliche Schlüssel wird vom AlgorithmIdentifier in PKCS #8 bestimmt):

  • RSA: MS_ENHANCED_PROV_W
  • DSA: MS_DEF_DSS_DH_PROV_W

Entsprechend wird die Schlüsselspezifikation wie folgt mithilfe der AttributeId mit OID 2.5.29.15 (szOID_KEY_USAGE) bestimmt:

Wenn ein CAPI-Schlüssel verwendet wird:

  • Wenn KEY_ENCIPHERMENT oder DATA_ENCIPHERMENT festgelegt ist, wird die Schlüsselspezifikation auf AT_KEYEXCHANGE festgelegt.
  • Wenn DIGITAL_SIGNATURE, CERT_SIGN oder CRL_SIGN festgelegt ist, wird die Schlüsselspezifikation auf AT_SIGNATURE festgelegt.

Wenn ein CNG-Schlüssel verwendet wird:

  • Wenn KEY_ENCIPHERMENT, DATA_ENCIPHERMENT, ENCIPHER_ONLY oder DECIPHER_ONLY festgelegt ist, wird die ncrypt-Schlüsselverwendung auf ALLOW_DECRYPT festgelegt.
  • Wenn DIGITAL_SIGNATURE, CERT_SIGN oder CRL_SIGN festgelegt ist, wird die Verwendung des ncrypt-Schlüssels auf ALLOW_SIGN festgelegt.
  • Wenn KEY_AGREEMENT festgelegt ist, wird die ncrypt-Schlüsselverwendung auf ALLOW_KEY_AGREEMENT festgelegt.

Wenn die AttributeId nicht vorhanden ist, wird der CAPI-Schlüsselwert für RSA oder DH auf AT_KEYEXCHANGE festgelegt, und der Algorithmus wird vom AlgorithmIdentifier in PKCS #8 bestimmt. Andernfalls wird der Algorithmus auf AT_SIGNATURE festgelegt. Für den CNG-Schlüsselwert wird die gesamte Verwendung des ncrypt-Schlüssels festgelegt.

Hinweis

Wenn im PFX-Paket ein ungültiger Anbietername vorhanden ist oder der Basis- oder erweiterte Kryptografieanbieter in diesem Registrierungsschlüssel nicht vorhanden ist: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, wird eine Anbietersuche vom Anbietertyp mithilfe des folgenden Registrierungsunterschlüssels ausgeführt: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.

Microsoft unterstützt nur zwei Verschlüsselungs-/Hashalgorithmen für den Import einer PFX:

  • TripleDES-SHA1
  • AES256-SHA256

Für einen der oben genannten Algorithmen ist die Verschlüsselung der Zertifikate optional.

Microsoft kann über die All Tasks>Yes, export the private key Auswahl einen PFX aus einem Zertifikatspeicher exportieren. Dort können Sie den Verschlüsselungs-/Hashalgorithmus auswählen, um einer dieser beiden Optionen zu entsprechen.

Sie können PowerShell verwenden, um eine PFX über Folgendes zu exportieren:

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption gibt den Algorithmus zum Verschlüsseln privater Schlüssel in der PFX-Datei an. Wenn dieser Parameter nicht angegeben ist, ist TripleDES_SHA1der Standardwert . Zulässige Werte für diesen Parameter:

Wert BESCHREIBUNG
TripleDES_SHA1 Private Schlüssel werden in der PFX-Datei mit Triple DES-Verschlüsselung verschlüsselt.
AES256_SHA256 Private Schlüssel werden in der PFX-Datei mit AES-256-Verschlüsselung verschlüsselt.

OpenSSL unterstützt die beiden oben genannten Algorithmen über die folgenden Befehle:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Die folgenden Befehle entsprechen den beiden vorherigen Befehlen, verschlüsseln die Zertifikate jedoch nicht:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe NONE -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile wincrypt.h
Bibliothek Crypt32.lib
DLL Crypt32.dll

Weitere Informationen

PFXExportCertStore

PFXExportCertStoreEx