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

數據流物件句柄的指標。

傳回值

傳回狀態代碼，指出函式的成功或失敗。可能的傳回碼包括但不限於下列各項。

傳回碼	Description
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
程式庫	NCrypt.lib
Dll	NCrypt.dll