NCryptStreamOpenToProtect-Funktion (ncryptprotect.h)

Artikel
03/06/2024

Die NCryptStreamOpenToProtect-Funktion öffnet ein Streamobjekt, das verwendet werden kann, um große Datenmengen mit einem bestimmten Schutzdeskriptor zu verschlüsseln. Rufen Sie NCryptStreamUpdate auf, um den Inhalt zu verschlüsseln. Um kleinere Nachrichten wie Schlüssel und Kennwörter zu verschlüsseln, rufen Sie NCryptProtectSecret auf.

Syntax

SECURITY_STATUS NCryptStreamOpenToProtect(
  [in]           NCRYPT_DESCRIPTOR_HANDLE   hDescriptor,
                 DWORD                      dwFlags,
  [in, optional] HWND                       hWnd,
  [in]           NCRYPT_PROTECT_STREAM_INFO *pStreamInfo,
  [out]          NCRYPT_STREAM_HANDLE       *phStream
);

Parameter

[in] hDescriptor

Handle des Schutzdeskriptors. Erstellen Sie das Handle, indem Sie NCryptCreateProtectionDescriptor aufrufen.

dwFlags

Das Flag kann null oder der folgende Wert sein.

Wert	Bedeutung
NCRYPT_SILENT_FLAG	Fordert an, dass der Schlüsseldienstanbieter keine Benutzeroberfläche anzeigt.

[in, optional] hWnd

Handle zum übergeordneten Fenster der Benutzeroberfläche, falls vorhanden, das angezeigt werden soll.

[in] pStreamInfo

Zeiger auf eine NCRYPT_PROTECT_STREAM_INFO Struktur, die die Adresse einer benutzerdefinierten Rückruffunktion zum Empfangen der verschlüsselten Daten und einen Zeiger auf benutzerdefinierte Kontextdaten enthält.

[out] phStream

Zeiger auf das Datenstromobjekthandle.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt. Mögliche Rückgabecodes umfassen folgendes, sind aber nicht darauf beschränkt.

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_BAD_FLAGS	Der dwFlags-Parameter muss null (0), NCRYPT_MACHINE_KEY_FLAG oder NCRYPT_SILENT_FLAG enthalten.
NTE_INVALID_HANDLE	Das durch den hDescriptor-Parameter angegebene Handle ist ungültig.
NTE_INVALID_PARAMETER	Die Parameter phStream und pStreamInfo dürfen nicht NULL sein. Die Rückruffunktion, auf die das pfnStreamOutput-Element der NCRYPT_PROTECT_STREAM_INFO Struktur verweist, auf die der pStreamInfo-Parameter verweist, kann nicht NULL sein.
NTE_NO_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um einen Datenstrom zuzuordnen.

Hinweise

Die NCryptStreamOpenToProtect-Funktion erstellt ein internes Streamobjekt, das zum Verschlüsseln großer Nachrichten verwendet werden kann. Sie können das Objekt nicht direkt verwenden. Stattdessen müssen Sie das von dieser Funktion zurückgegebene Objekthandle verwenden.

Rufen Sie diese Funktion auf, bevor Sie die NCryptStreamUpdate-Funktion aufrufen. Wenn Sie eine große Datei verschlüsseln, verwenden Sie NCryptStreamUpdate in einer Schleife, die die Datei Block für Block durchläuft, jeden Block verschlüsselt, während er voranschreitet, und benachrichtigen Sie Ihren Rückruf, wenn jeder Block abgeschlossen ist. Weitere Informationen finden Sie unter NCryptStreamUpdate.

Die NCryptStreamOpenToProtect-Funktion schreibt die unverschlüsselte Schutzdeskriptorregelzeichenfolge in den Header des Streamobjekts, sodass NCryptStreamOpenToUnprotect die Entschlüsselung des Datenstroms mithilfe der gleichen Schutzvorrichtung starten kann, die während der Verschlüsselung verwendet wurde.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ncryptprotect.h
Bibliothek	NCrypt.lib
DLL	NCrypt.dll