Funzione NCryptStreamOpenToProtect (ncryptprotect.h)

Articolo
02/29/2024

La funzione NCryptStreamOpenToProtect apre un oggetto flusso che può essere usato per crittografare grandi quantità di dati in un descrittore di protezione specifico. Chiamare NCryptStreamUpdate per crittografare il contenuto. Per crittografare messaggi più piccoli, ad esempio chiavi e password, chiamare NCryptProtectSecret.

Sintassi

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

Parametri

[in] hDescriptor

Handle del descrittore di protezione. Creare l'handle chiamando NCryptCreateProtectionDescriptor.

dwFlags

Il flag può essere zero o il valore seguente.

Valore	Significato
NCRYPT_SILENT_FLAG	Richiede che il provider di servizi chiave non visualizzi un'interfaccia utente.

[in, optional] hWnd

Gestire nella finestra padre dell'interfaccia utente, se presente, da visualizzare.

[in] pStreamInfo

Puntatore a una struttura NCRYPT_PROTECT_STREAM_INFO che contiene l'indirizzo di una funzione di callback definita dall'utente per ricevere i dati crittografati e un puntatore ai dati di contesto definiti dall'utente.

[out] phStream

Puntatore all'handle dell'oggetto flusso.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione. I codici restituiti possibili includono, a titolo esemplificativo, quanto segue.

Codice restituito	Descrizione
ERROR_SUCCESS	La funzione ha avuto esito positivo.
NTE_BAD_FLAGS	Il parametro dwFlags deve contenere zero (0), NCRYPT_MACHINE_KEY_FLAG o NCRYPT_SILENT_FLAG.
NTE_INVALID_HANDLE	L'handle specificato dal parametro hDescriptor non è valido.
NTE_INVALID_PARAMETER	I parametri phStream e pStreamInfo non possono essere NULL. La funzione di callback a cui punta il membro pfnStreamOutput della struttura NCRYPT_PROTECT_STREAM_INFO a cui punta il parametro pStreamInfo non può essere NULL.
NTE_NO_MEMORY	Memoria insufficiente per allocare un flusso di dati.

Commenti

La funzione NCryptStreamOpenToProtect crea un oggetto flusso interno che può essere usato per crittografare messaggi di grandi dimensioni. Non è possibile utilizzare direttamente l'oggetto . È invece necessario usare l'handle dell'oggetto restituito da questa funzione.

Chiamare questa funzione prima di chiamare la funzione NCryptStreamUpdate . Se si crittografa un file di grandi dimensioni, usare NCryptStreamUpdate in un ciclo che avanza attraverso il blocco di file per blocco, crittografando ogni blocco mentre avanza e notificando il callback al termine di ogni blocco. Per altre informazioni, vedere NCryptStreamUpdate.

La funzione NCryptStreamOpenToProtect scrive la stringa della regola del descrittore di protezione non crittografata nell'intestazione dell'oggetto flusso in modo che NCryptStreamOpenToUnprotect possa avviare la decrittografia del flusso usando la stessa protezione usata durante la crittografia.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ncryptprotect.h
Libreria	NCrypt.lib
DLL	NCrypt.dll