bCryptDecrypt 函式 (bcrypt.h)

  • 發行項

BCryptDecrypt函式會解密資料區塊。

語法

NTSTATUS BCryptDecrypt(
  [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 函式以取得 BCRYPT_BLOCK_LENGTH 屬性，即可取得 IV 的必要大小。 這會為演算法提供區塊的大小，這也是 IV 的大小。

[in] cbIV

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

[out, optional] pbOutput

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

如果此參數為 Null， BCryptDecrypt 函式會計算 在 pbInput 參數中傳遞之加密資料的純文字所需的大小。 在此情況下， 由STATUS_SUCCESS參數 指向的位置會包含此大小，而且函式會 傳回STATUS_SUCCESS。

如果 pbOutput 和 pbInput 參數的值都是 Null，除非使用已驗證的加密演算法，否則會傳回錯誤。 在後者的情況下，系統會將呼叫視為長度為零資料的已驗證加密呼叫，而驗證標籤會在 pPaddingInfo 參數中傳遞。

[in] cbOutput

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

[out] pcbResult

ULONG變數的指標，可接收復制到pbOutput緩衝區的位元組數目。 如果 pbOutput 為 Null，這會接收純文字所需的大小，以位元組為單位。

[in] dwFlags

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

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

值 意義
BCRYPT_BLOCK_PADDING
 資料在加密時已填補到下一個區塊大小。 如果此旗標搭配 BCryptEncrypt 函式使用，則也必須在此函式中指定它。 此旗標不得與 AES-CCM 和 AES-GCM () 的已驗證加密模式搭配使用。
 

如果金鑰是非對稱金鑰，這可以是下列其中一個值。

值 意義
BCRYPT_PAD_NONE
 請勿使用任何填補。 不會使用 pPaddingInfo 參數。 cbInput參數必須是演算法區塊大小的倍數。

您可以呼叫 BCryptGetProperty 函式來取得區塊大小，以取得 金鑰的BCRYPT_BLOCK_LENGTH 屬性。 這會為演算法提供區塊的大小。
BCRYPT_PAD_OAEP
 加密資料時，會使用最佳非對稱加密填補 (OAEP) 配置。 pPaddingInfo參數是BCRYPT_OAEP_PADDING_INFO結構的指標。
BCRYPT_PAD_PKCS1
 資料在加密時會以亂數字填補。 不會使用 pPaddingInfo 參數。

傳回值

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

可能的傳回碼包括但不限於下列專案。

傳回碼 Description
STATUS_SUCCESS
 函式成功。
STATUS_AUTH_TAG_MISMATCH
 計算驗證標記不符合 pPaddingInfo 參數中提供的值。
STATUS_BUFFER_TOO_SMALL
 cbOutput參數所指定的大小不夠大，無法保存加密文字。
STATUS_INVALID_BUFFER_SIZE
 cbInput參數不是演算法區塊大小的倍數，而且dwFlags參數中未指定BCRYPT_BLOCK_PADDING旗標。
STATUS_INVALID_HANDLE
 hKey參數中的金鑰控制碼無效。
STATUS_INVALID_PARAMETER
 一或多個參數無效。
STATUS_NOT_SUPPORTED
 演算法不支援解密。

備註

pbInput和pbOutput參數可以相等。 在此情況下，此函式會就地執行解密。 如果 pbInput 和 pbOutput 不相等，則兩個緩衝區可能不會重迭。

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

若要在核心模式中呼叫此函式，請使用 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

另請參閱

BCryptEncrypt