共用方式為

BCryptEncrypt 函式 (bcrypt.h)

  • 發行項

BCryptEncrypt 函式會加密數據區塊。

語法

NTSTATUS BCryptEncrypt(
  [in, out]           BCRYPT_KEY_HANDLE hKey,
  [in]                PUCHAR            pbInput,
  [in]                ULONG             cbInput,
  [in, optional]      VOID              *pPaddingInfo,
  [in, out, optional] PUCHAR            pbIV,
  [in]                ULONG             cbIV,
  [out, optional]     PUCHAR            pbOutput,
  [in]                ULONG             cbOutput,
  [out]               ULONG             *pcbResult,
  [in]                ULONG             dwFlags
);

參數

[in, out] hKey

用來加密數據的金鑰句柄。 此句柄是從其中一個密鑰建立函式取得，例如 BCryptGenerateSymmetricKey、 BCryptGenerateKeyPair 或 BCryptImportKey。

[in] pbInput

緩衝區的位址，其中包含要加密的純文本。 cbInput 參數包含要加密的純文字大小。 如需詳細資訊，請參閱＜備註＞。

[in] cbInput

要加密之 pbInput 緩衝區中的位元元組數目。

[in, optional] pPaddingInfo

包含填補資訊之結構的指標。 此參數僅適用於非對稱金鑰和已驗證加密模式。 如果使用已驗證的加密模式，此參數必須指向 BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO 結構。 如果使用非對稱密鑰，這個參數所指向的結構類型取決於 dwFlags 參數的值。 否則，參數必須設定為 NULL。

[in, out, optional] pbIV

緩衝區的位址，其中包含加密期間要使用的 初始化向量 (IV) 。 cbIV 參數包含這個緩衝區的大小。 此函式會修改此緩衝區的內容。 如果您需要稍後重複使用IV，請務必先建立此緩衝區的複本，再呼叫此函式。

此參數是選擇性的，如果沒有使用IV，則可以是 NULL 。

您可以藉由呼叫 BCryptGetProperty 函式來取得 IV 的必要大小，以取得 BCRYPT_BLOCK_LENGTH 屬性。 這會提供演算法的區塊大小，這也是IV的大小。

[in] cbIV

pbIV 緩衝區的大小，以位元組為單位。

[out, optional] pbOutput

接收此函式所產生 之加密文字 的緩衝區位址。 cbOutput 參數包含這個緩衝區的大小。 如需詳細資訊，請參閱＜備註＞。

如果此參數為 NULL，BCryptEncrypt 函式會計算在 pbInput 參數中傳遞之數據的加密文字所需的大小。 在此情況下， 由 azureResult 參數指向的位置會包含這個大小，而且函式會傳回 STATUS_SUCCESS。 pPaddingInfo 參數未修改。

如果 pbOutput 和 pbInput 參數的值都是 NULL，除非使用已驗證的加密演算法，否則會傳回錯誤。 在後者的情況下，呼叫會被視為具有零長度數據的已驗證加密呼叫，並在 pPaddingInfo 參數中傳回驗證標記。

[in] cbOutput

pbOutput 緩衝區的大小，以位元組為單位。 如果 pbOutput 參數為 NULL，則會忽略此參數。

[out] pcbResult

ULONG 變數的指標，接收複製到 pbOutput 緩衝區的位元組數目。 如果 pbOutput 為 NULL，這會接收加密文字所需的大小，以位元組為單位。

[in] dwFlags

一組旗標，可修改此函式的行為。 允許的旗標集取決於 hKey 參數所指定的索引鍵類型。

如果密鑰是對稱金鑰，這可以是零或下列值。

值 意義
BCRYPT_BLOCK_PADDING
 允許加密演算法將數據填補到下一個區塊大小。 如果未指定此旗標， cbInput 參數中指定的純文字大小必須是演算法區塊大小的倍數。

您可以呼叫 BCryptGetProperty 函式來取得區塊大小，以取得 索引鍵的 BCRYPT_BLOCK_LENGTH 屬性。 這會提供演算法區塊的大小。

此旗標不得與已驗證的加密模式搭配使用， (AES-CCM 和 AES-GCM) 。
 

如果索引鍵是非對稱密鑰，這可以是下列其中一個值。

值 意義
BCRYPT_PAD_NONE
 請勿使用任何填補。 不會使用 pPaddingInfo 參數。 cbInput 參數中指定的純文字大小必須是演算法區塊大小的倍數。
BCRYPT_PAD_OAEP
 使用最佳非對稱加密填補 (OAEP) 配置。 pPaddingInfo 參數是BCRYPT_OAEP_PADDING_INFO結構的指標。
BCRYPT_PAD_PKCS1
 數據會以隨機數位填補，以四捨五入區塊大小。 不會使用 pPaddingInfo 參數。

傳回值

傳回狀態代碼，指出函式的成功或失敗。

可能的傳回碼包括但不限於下列各項。

傳回碼 Description
STATUS_SUCCESS
 函式成功。
STATUS_BUFFER_TOO_SMALL
 cbOutput 參數所指定的大小不夠大，無法保存加密文字。
STATUS_INVALID_BUFFER_SIZE
 cbInput 參數不是演算法區塊大小的倍數，而且在 dwFlags 參數中未指定BCRYPT_BLOCK_PADDING或BCRYPT_PAD_NONE旗標。
STATUS_INVALID_HANDLE
 hKey 參數中的金鑰句柄無效。
STATUS_INVALID_PARAMETER
 一或多個參數無效。
STATUS_NOT_SUPPORTED
 演算法不支援加密。

備註

pbInput 和 pbOutput 參數可以相等。 在此情況下，此函式會就地執行加密。 加密的數據大小可能大於未加密的數據大小，因此緩衝區必須夠大，才能保存加密的數據。 如果 pbInput 和 pbOutput 不相等，則兩個緩衝區可能不會重疊。

根據提供者支持的處理器模式， BCryptEncrypt 可以從使用者模式或核心模式呼叫。 核心模式呼叫端可以在 IRQL PASSIVE_LEVEL 或DISPATCH_LEVELIRQL 上執行。 如果目前的 IRQL 層級 DISPATCH_LEVEL， 則 hKey 參數中提供的句柄必須衍生自以 BCRYPT_PROV_DISPATCH 旗標開啟的提供者所傳回的演算法句柄，而且傳遞至 BCryptEncrypt 函式的任何指標都必須參考非分頁 (或鎖定) 記憶體。

若要在核心模式中呼叫此函式，請使用 Cng.lib，這是驅動程式開發工具包 (DDK) 的一部分。 Windows Server 2008 和 Windows Vista： 若要在核心模式中呼叫此函式，請使用 Ksecdd.lib。

規格需求

需求 值
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 bcrypt.h
程式庫 Bcrypt.lib
Dll Bcrypt.dll

另請參閱

BCryptDecrypt