NCryptStreamOpenToProtect function (ncryptprotect.h)

Article
10/13/2021

The NCryptStreamOpenToProtect function opens a stream object that can be used to encrypt large amounts of data to a given protection descriptor. Call NCryptStreamUpdate to encrypt the content. To encrypt smaller messages such as keys and passwords, call NCryptProtectSecret.

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

Parameters

[in] hDescriptor

Handle of the protection descriptor. Create the handle by calling NCryptCreateProtectionDescriptor.

dwFlags

The flag can be zero or the following value.

Value	Meaning
NCRYPT_SILENT_FLAG	Requests that the key service provider not display a user interface.

[in, optional] hWnd

Handle to the parent window of the user interface, if any, to be displayed.

[in] pStreamInfo

Pointer to an NCRYPT_PROTECT_STREAM_INFO structure that contains the address of a user defined callback function to receive the encrypted data and a pointer to user-defined context data.

[out] phStream

Pointer to the stream object handle.

Return value

Returns a status code that indicates the success or failure of the function. Possible return codes include, but are not limited to, the following.

Return code	Description
ERROR_SUCCESS	The function was successful.
NTE_BAD_FLAGS	The dwFlags parameter must contain zero (0), NCRYPT_MACHINE_KEY_FLAG, or NCRYPT_SILENT_FLAG.
NTE_INVALID_HANDLE	The handle specified by the hDescriptor parameter is not valid.
NTE_INVALID_PARAMETER	The phStream and pStreamInfo parameters cannot be NULL. The callback function pointed to by the pfnStreamOutput member of the NCRYPT_PROTECT_STREAM_INFO structure pointed to by the pStreamInfo parameter cannot be NULL.
NTE_NO_MEMORY	There was insufficient memory to allocate a data stream.

Remarks

The NCryptStreamOpenToProtect function creates an internal stream object that can be used to encrypt large messages. You cannot use the object directly. Instead, you must use the object handle returned by this function.

Call this function before calling the NCryptStreamUpdate function. If you are encrypting a large file, use NCryptStreamUpdate in a loop that advances through the file block by block, encrypting each block as it advances and notifying your callback when each block is finished. For more information, see NCryptStreamUpdate.

The NCryptStreamOpenToProtect function writes the unencrypted protection descriptor rule string to the stream object header so that NCryptStreamOpenToUnprotect will be able to start the decrypting the stream by using the same protector used during encryption.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	ncryptprotect.h
Library	NCrypt.lib
DLL	NCrypt.dll