Freigeben über

NCryptCreatePersistedKey-Funktion (ncrypt.h)

  • Artikel

Die NCryptCreatePersistedKey-Funktion erstellt einen neuen Schlüssel und speichert ihn im angegebenen Schlüsselspeicheranbieter. Nachdem Sie mithilfe dieser Funktion einen Schlüssel erstellt haben, können Sie die NCryptSetProperty-Funktion verwenden, um die zugehörigen Eigenschaften festzulegen. Der Schlüssel kann jedoch erst verwendet werden, wenn die NCryptFinalizeKey-Funktion aufgerufen wird.

Syntax

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

Parameter

[in] hProvider

Das Handle des Schlüsselspeicheranbieters, in dem der Schlüssel erstellt werden soll. Dieses Handle wird mithilfe der NCryptOpenStorageProvider-Funktion abgerufen.

[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. Um die Schlüsseldatei auf dem Datenträger zu löschen, übergeben Sie das Handle an die NCryptDeleteKey-Funktion . Dadurch wird auch das Handle freigegeben. Daher können Anwendungen das Handle entweder an NCryptFreeObject oder NCryptDeleteKey übergeben, aber nicht an beide.

[in] pszAlgId

Ein Zeiger auf eine Unicode-Zeichenfolge mit Null-Ende, die den Bezeichner des kryptografischen Algorithmus zum Erstellen des Schlüssels enthält. Dies kann einer der Standardmäßigen CNG-Algorithmusbezeichner oder der Bezeichner für einen anderen registrierten Algorithmus sein.

[in, optional] pszKeyName

Ein Zeiger auf eine Unicode-Zeichenfolge, die null beendet ist und den Namen des Schlüssels enthält. Wenn dieser Parameter NULL ist, erstellt diese Funktion einen kurzlebigen Schlüssel, der nicht beibehalten wird.

[in] dwLegacyKeySpec

Ein Legacybezeichner, der den Typ des Schlüssels angibt. Mögliche Werte:

Wert Bedeutung
AT_KEYEXCHANGE Der Schlüssel ist ein Schlüsselaustauschschlüssel.
AT_SIGNATURE Der Schlüssel ist ein Signaturschlüssel.
0 Der Schlüssel ist keiner der oben genannten Typen.

[in] dwFlags

Ein Satz von Flags, die das Verhalten dieser Funktion ändern. Dies kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein:

Wert Bedeutung
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_REQUIRE_VBS_FLAG Gibt an, dass ein Schlüssel mit virtualisierungsbasierter Sicherheit (VBS) geschützt werden muss. Standardmäßig wird dadurch ein dauerhafter Schlüssel erstellt, der über den Start hinweg auf dem Datenträger gespeichert ist und über Neustartzyklen hinweg beibehalten wird.

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. Standardmäßig wird dadurch ein auf dem Datenträger gespeicherter dauerhafter Cross-Boot-Schlüssel erstellt, der über Neustartzyklen hinweg beibehalten wird.

Der Vorgang generiert einen softwareisolierten Schlüssel, wenn VBS nicht verfügbar ist. (*Siehe Hinweise)
NCRYPT_USE_PER_BOOT_KEY_FLAG Ein zusätzliches Flag, das zusammen mit NCRYPT_REQUIRE_VBS_FLAG oder NCRYPT_PREFER_VBS_FLAG verwendet werden kann. Weist Virtualisierungsbasierte Sicherheit (VBS) an, den Clientschlüssel mit einem Pro-Boot-Schlüssel zu schützen, der auf dem Datenträger gespeichert ist, aber nicht über Startzyklen hinweg wiederverwendet werden kann. (*Siehe Hinweise)

Rückgabewert

Gibt einen Statuscode 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.

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.

Wenn Sie ein RSA-Schlüsselpaar erstellen, können Sie den Schlüssel auch im Legacyspeicher speichern lassen, sodass er mit der CryptoAPI verwendet werden kann, indem Sie das NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG-Flag an die NCryptFinalizeKey-Funktion übergeben, wenn der Schlüssel abgeschlossen ist.

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.

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

NCryptDeleteKey

NCryptFinalizeKey

NCryptImportKey