NCryptStreamOpenToUnprotect function

The NCryptStreamOpenToUnprotect function opens a stream object that can be used to decrypt large amounts of data to the same protection descriptor used for encryption. Call NCryptStreamUpdate to perform the decryption. To decrypt smaller messages such as keys and passwords, call NCryptUnprotectSecret.

Syntax


NTSTATUS WINAPI NCryptStreamOpenToUnprotect(
  _In_      NCRYPT_PROTECT_STREAM_INFO *pStreamInfo,
  DWORD dwFlags,
  _In_opt_  HWND hWnd,
  _Out_     NCRYPT_STREAM_HANDLE *phStream
);

Parameters

pStreamInfo [in]

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

dwFlags

A flag that specifies additional information for the key service provider. This can be zero or the following value.

ValueMeaning
NCRYPT_SILENT_FLAG

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

 

hWnd [in, optional]

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

phStream [out]

Pointer to the handle of the decrypted stream of data.

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 codeDescription
ERROR_SUCCESS

The function was successful.

NTE_BAD_FLAGS

The dwFlags parameter must contain zero (0) or NCRYPT_SILENT_FLAG.

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 NCryptStreamOpenToUnprotect 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 NCryptStreamOpenToUnprotect function retrieves the unencrypted protection descriptor rule string from the stream header. The rule string is placed in the header by the NCryptStreamOpenToUnprotect function.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

NCryptprotect.h

Library

NCrypt.lib

DLL

NCrypt.dll

See also

CNG DPAPI Functions
NCRYPT_PROTECT_STREAM_INFO
NCryptStreamClose
NCryptStreamOpenToProtect
NCryptStreamUpdate

 

 

Community Additions

ADD
Show:
© 2014 Microsoft