NCryptStreamOpenToProtect 函数 (ncryptprotect.h)

项目
02/29/2024

NCryptStreamOpenToProtect 函数打开一个流对象，该对象可用于将大量数据加密到给定的保护描述符。调用 NCryptStreamUpdate 以加密内容。若要加密较小的消息（如密钥和密码），请调用 NCryptProtectSecret。

语法

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

参数

[in] hDescriptor

保护描述符的句柄。通过调用 NCryptCreateProtectionDescriptor 创建句柄。

dwFlags

标志可以是零或以下值。

值	含义
NCRYPT_SILENT_FLAG	请求密钥服务提供程序不显示用户界面。

[in, optional] hWnd

要显示的用户界面的父窗口的句柄（如果有）。

[in] pStreamInfo

指向 NCRYPT_PROTECT_STREAM_INFO 结构的指针，该结构包含用于接收加密数据的用户定义的回调函数的地址，以及指向用户定义的上下文数据的指针。

[out] phStream

指向流对象句柄的指针。

返回值

返回指示函数成功或失败的状态代码。可能的返回代码包括但不限于以下内容。

返回代码	说明
ERROR_SUCCESS	函数成功。
NTE_BAD_FLAGS	dwFlags 参数必须包含零 (0) 、 NCRYPT_MACHINE_KEY_FLAG 或 NCRYPT_SILENT_FLAG。
NTE_INVALID_HANDLE	hDescriptor 参数指定的句柄无效。
NTE_INVALID_PARAMETER	phStream 和 pStreamInfo 参数不能为 NULL。 pStreamInfo 参数指向的 NCRYPT_PROTECT_STREAM_INFO 结构的 pfnStreamOutput 成员指向的回调函数不能为 NULL。
NTE_NO_MEMORY	内存不足，无法分配数据流。

注解

NCryptStreamOpenToProtect 函数创建可用于加密大型消息的内部流对象。不能直接使用对象。相反，必须使用此函数返回的对象句柄。

在调用 NCryptStreamUpdate 函数之前调用此函数。如果要加密大型文件，请在循环中使用 NCryptStreamUpdate ，该循环逐个通过文件块，在前进时加密每个块，并在每个块完成时通知回调。有关详细信息，请参阅 NCryptStreamUpdate。

NCryptStreamOpenToProtect 函数将未加密的保护描述符规则字符串写入流对象标头，以便 NCryptStreamOpenToUnprotect 能够使用加密期间使用的同一个保护程序开始解密流。

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	ncryptprotect.h
Library	NCrypt.lib
DLL	NCrypt.dll