NCryptImportKey-Funktion (ncrypt.h)

Die NCryptImportKey-Funktion importiert einen Kryptografie-API: CNG-Schlüssel (Next Generation) aus einem Speicher-BLOB.

Syntax

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

Die Parameter

[in] hProvider

Das Handle des Schlüsselspeicheranbieters.

[in, optional] hImportKey

Das Handle des kryptografischen Schlüssels , mit dem die Schlüsseldaten im importierten Schlüssel-BLOB verschlüsselt wurden. Dies muss ein Handle für denselben Schlüssel sein, der im hExportKey-Parameter der NCryptExportKey-Funktion übergeben wurde. Wenn dieser Parameter NULL ist, wird davon ausgegangen, dass der Schlüssel-BLOB nicht verschlüsselt wird.

[in] pszBlobType

Eine mit Null beendete Unicode-Zeichenfolge, die einen Bezeichner enthält, der das Format des Schlüssel-BLOB angibt. Diese Formate sind spezifisch für einen bestimmten Schlüsselspeicheranbieter. Informationen zu den BLOB-Formaten, die von Microsoft-Anbietern unterstützt werden, finden Sie in den Hinweisen.

[in, optional] pParameterList

Die Adresse einer NCryptBufferDesc-Struktur , die auf ein Array von Puffern verweist, die Parameterinformationen für den Schlüssel enthalten.

[out] phKey

Die Adresse einer NCRYPT_KEY_HANDLE Variablen, die das Handle des Schlüssels empfängt. Wenn Sie mit der Verwendung dieses Handle fertig sind, lassen Sie es los, indem Sie es an die NCryptFreeObject-Funktion übergeben.

[in] pbData

Die Adresse eines Puffers, der den zu importierenden Schlüssel-BLOB enthält. Der cbData-Parameter enthält die Größe dieses Puffers.

[in] cbData

Die Größe des PbData-Puffers in Bytes.

[in] dwFlags

Flags, die das Funktionsverhalten ändern. Dies kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein. Der Satz gültiger Flags ist spezifisch für jeden Schlüsselspeicheranbieter.

Rückgabewert

Gibt einen Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes umfassen, sind jedoch nicht beschränkt auf Folgendes:

Bemerkungen

Ein Dienst darf diese Funktion nicht über die StartService-Funktion aufrufen. Wenn ein Dienst diese Funktion über die StartService-Funktion aufruft, kann ein Deadlock auftreten, und der Dienst reagiert möglicherweise nicht mehr.

In den folgenden Abschnitten werden spezifische Verhaltensweisen für die Microsoft-Schlüsselspeicheranbieter beschrieben:

• Microsoft Software KSP
• Microsoft Smartcard-KSP

Microsoft Software KSP

Details zu den meisten pszBlobType-Parametern, die vom Microsoft-Software-KSP unterstützt werden, finden Sie unter NCryptImportKey.

Wenn kein Schlüsselname angegeben wird, behandelt der Microsoft Software-KSP den Schlüssel als kurzlebig und speichert ihn nicht dauerhaft. Für den NCRYPT_OPAQUETRANSPORT_BLOB Typ wird der Schlüsselname im BLOB gespeichert, wenn er exportiert wird. Bei anderen BLOB-Formaten kann der Name in einem NCRYPTBUFFER_PKCS_KEY_NAME Pufferparameter innerhalb des pParameterList-Parameters angegeben werden.

Unter Windows Server 2008 und Windows Vista können nur Schlüssel, die als PKCS #7 Envelope BLOBs (NCRYPT_PKCS7_ENVELOPE_BLOB) oder PKCS #8 private Key BLOBs (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) importiert werden, mithilfe der oben genannten Methode beibehalten werden. Verwenden Sie zum Speichern von Schlüsseln, die über andere BLOB-Typen auf diesen Plattformen importiert werden, die in Schlüsselimport und -export dokumentiert ist.

Die folgenden Flags werden von diesem KSP unterstützt.

Microsoft Smartcard-KSP

Die Gruppe der wichtigsten BLOB-Formate und Flags, die von diesem KSP unterstützt werden, ist identisch mit dem Satz, der vom Microsoft-Software-KSP unterstützt wird.

Unter Windows Server 2008 und Windows Vista importiert der Microsoft Smart Card KSP alle Schlüssel in den Microsoft Software KSP. Daher können Schlüssel nicht mithilfe dieser API auf einer Smartcard beibehalten werden, und die Anleitungen im obigen Abschnitt gelten beim Versuch, Schlüssel innerhalb des Microsoft Software-KSP beizubehalten.

Unter Windows Server 2008 R2 und Windows 7 kann der Microsoft SmartCard Key Storage Provider einen privaten Schlüssel in eine Smartcard importieren, vorausgesetzt, die folgenden Bedingungen sind erfüllt:

• Der Schlüsselcontainername auf der Karte ist gültig.
• Das Importieren privater Schlüssel wird von der Smartcard unterstützt.
• Die folgenden beiden Registrierungsschlüssel werden auf ein DWORD von 0x1:
  • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base SmartCard Crypto Provider\AllowPrivateExchangeKeyImport
  • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base SmartCard Crypto Provider\AllowPrivateSignatureKeyImport

Wenn der Schlüsselcontainername NULL ist, behandelt der Microsoft Smart Card KSP den Schlüssel als kurzlebig und importiert ihn in den Microsoft Software KSP.

Zusätzliche Hardwareanforderungen für VBS-Schlüssel

Obwohl auf Ihrem Computer möglicherweise das entsprechende Betriebssystem installiert ist, müssen die folgenden zusätzlichen Hardwareanforderungen erfüllt sein, um VBS zum Generieren und Schützen von Schlüsseln zu verwenden.

• VBS aktiviert (siehe Virtualisierungsbasierte Sicherheit (VBS))
• TPM aktiviert
  • Für Bare-Metal-Umgebungen ist TPM 2.0 erforderlich.
  • Für VM-Umgebungen wird vTPM (Virtual TPM) unterstützt.
• BIOS sollte mit SecureBoot-Profil auf UEFI aktualisiert werden

Weitere Informationen zu Hardwareanforderungen:

• VBS verfügt über mehrere Hardwareanforderungen für die Ausführung, einschließlich Hyper-V (Windows-Hypervisor), der 64-Bit-Architektur und der IOMMU-Unterstützung. Die vollständige Liste der VBS-Hardwareanforderungen finden Sie hier.
• Anforderungen für ein hochsicheres Gerät finden Sie hier.

Anforderungen

Siehe auch

NCryptBuffer

NCryptCreatePersistedKey