NCryptImportKey-Funktion (ncrypt.h)

  • Artikel

Die NCryptImportKey-Funktion importiert einen CNG-Schlüssel (Cryptography API: Next Generation) aus einem Speicherblob.

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
);

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üsselblob 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 das Schlüsselblob nicht verschlüsselt ist.

[in] pszBlobType

Eine mit NULL endende Unicode-Zeichenfolge, die einen Bezeichner enthält, der das Format des Schlüsselblobs angibt. Diese Formate sind spezifisch für einen bestimmten Schlüsselspeicheranbieter. Informationen zu den von Microsoft-Anbietern unterstützten BLOB-Formaten finden Sie unter Hinweise.

[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 Handles fertig sind, geben Sie es frei, indem Sie es an die NCryptFreeObject-Funktion übergeben.

[in] pbData

Die Adresse eines Puffers, der das zu importierende Schlüsselblob 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 für jeden Schlüsselspeicheranbieter spezifisch.

Wert Bedeutung
NCRYPT_SILENT_FLAG Fordert an, dass der Schlüsseldienstanbieter (Key Service Provider, KSP) keine Benutzeroberfläche anzeigt. Wenn der Anbieter die Benutzeroberfläche für den Betrieb anzeigen muss, schlägt der Aufruf fehl, und der KSP sollte den NTE_SILENT_CONTEXT Fehlercode als letzten Fehler festlegen.
NCRYPT_REQUIRE_VBS_FLAG Gibt an, dass ein Schlüssel mit virtualisierungsbasierter Sicherheit (VBS) geschützt werden muss.

Der Vorgang schlägt fehl, wenn VBS nicht verfügbar ist. (*Siehe Hinweise)
NCRYPT_PREFER_VBS_FLAG Gibt an, dass ein Schlüssel mit virtualisierungsbasierter Sicherheit (VBS) geschützt werden soll.

Der Vorgang generiert einen softwareisolierten Schlüssel, wenn VBS nicht verfügbar ist. (*Siehe Hinweise)

Rückgabewert

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

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode Beschreibung
ERROR_SUCCESS Die Funktion war erfolgreich.
NTE_BAD_FLAGS Der dwFlags-Parameter enthält einen ungültigen Wert.
NTE_EXISTS Ein Schlüssel mit dem angegebenen Namen ist bereits vorhanden, und die NCRYPT_OVERWRITE_KEY_FLAG wurde nicht angegeben.
NTE_INVALID_HANDLE Der hProvider-Parameter ist ungültig.
NTE_INVALID_PARAMETER Mindestens ein Parameter ist ungültig.
NTE_NO_MEMORY Ein Speicherbelegungsfehler ist aufgetreten.
NTE_VBS_UNAVAILABLE VBS ist nicht verfügbar.
NTE_VBS_CANNOT_DECRYPT_KEY Fehler beim Entschlüsselungsvorgang bei VBS.

Hinweise

Wichtig

Informationen zu VBS-Flags beziehen sich auf Vorabrelease-Produkte, die vor der kommerziellen Veröffentlichung wesentlich geändert werden können. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Ein Dienst darf diese Funktion nicht über seine StartService-Funktion aufrufen. Wenn ein Dienst diese Funktion über seine 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

Die folgenden Konstanten werden vom Microsoft-Software-KSP für den pszBlobType-Parameter unterstützt.

Wenn kein Schlüsselname angegeben wird, behandelt der Microsoft-Software-KSP den Schlüssel als kurzlebig und speichert ihn nicht dauerhaft. Für den typ NCRYPT_OPAQUETRANSPORT_BLOB wird der Schlüsselname beim Exportieren im BLOB gespeichert. 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 obigen Methode beibehalten werden. Verwenden Sie zum Beibehalten von Schlüsseln, die über andere BLOB-Typen auf diesen Plattformen importiert wurden, die -Methode, die unter Schlüsselimport und -export dokumentiert ist.

Die folgenden Flags werden von diesem KSP unterstützt.

Begriff BESCHREIBUNG
NCRYPT_NO_KEY_VALIDATION Überprüfen Sie nicht den öffentlichen Teil des Schlüsselpaars. Dieses Flag gilt nur für öffentliche/private Schlüsselpaare.
NCRYPT_DO_NOT_FINALIZE_FLAG Schließen Sie den Schlüssel nicht ab. Diese Option ist nützlich, wenn Sie eigenschaften des Schlüssels nach dem Importieren hinzufügen oder ändern müssen. Sie müssen den Schlüssel abschließen, bevor er verwendet werden kann, indem Sie das Schlüsselhandle an die NCryptFinalizeKey-Funktion übergeben. Dieses Flag wird für die privaten Schlüssel PKCS #7 und PKCS #8 unterstützt, aber nicht für öffentliche Schlüssel.
NCRYPT_MACHINE_KEY_FLAG Der Schlüssel gilt für den lokalen Computer. Wenn dieses Flag nicht vorhanden ist, gilt der Schlüssel für den aktuellen Benutzer.
NCRYPT_OVERWRITE_KEY_FLAG Wenn im Container bereits ein Schlüssel mit dem angegebenen Namen vorhanden ist, wird der vorhandene Schlüssel überschrieben. Wenn dieses Flag nicht angegeben ist und bereits ein Schlüssel mit dem angegebenen Namen vorhanden ist, gibt diese Funktion NTE_EXISTS zurück.
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG Speichern Sie den Schlüssel auch im älteren Speicher. Dadurch kann der Schlüssel mit der CryptoAPI verwendet werden. Dieses Flag gilt nur für RSA-Schlüssel.

Microsoft SmartCard KSP

Der Satz 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 in einem intelligenten Karte mithilfe dieser API beibehalten werden, und die Anleitung im obigen Abschnitt gilt für den Versuch, Schlüssel innerhalb des Microsoft Software KSP beizubehalten.

Unter Windows Server 2008 R2 und Windows 7 kann der Microsoft Smartcard Key Storage-Anbieter einen privaten Schlüssel in eine intelligente Karte importieren, sofern die folgenden Bedingungen erfüllt sind:

  • Der Name des Schlüsselcontainers auf der Karte ist gültig.
  • Das Importieren privater Schlüssel wird von der intelligenten Karte unterstützt.
  • Die folgenden beiden Registrierungsschlüssel sind auf ein DWORD von 0x1festgelegt:
    • 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 möglicherweise das entsprechende Betriebssystem auf Ihrem Computer 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 auf UEFI mit SecureBoot-Profil aktualisiert werden

Weitere Informationen zu Hardwareanforderungen:

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile ncrypt.h
Bibliothek Ncrypt.lib
DLL Ncrypt.dll

Weitere Informationen

NCryptBuffer