CryptDecrypt 函式（wincrypt.h）

發行項
07/16/2024

重要此 API 已被取代。新的和現有的軟體應該開始使用密碼編譯新一代 API。 Microsoft 在未來版本中可能會移除此 API。

CryptDecrypt 函式會使用 CryptEncrypt 函式來解密先前加密的數據。

支援 Secure/Multipurpose Internet Mail Extensions （S/MIME）電子郵件互操作性的重要變更已對影響信封郵件處理之 CryptoAPI 進行。如需詳細資訊，請參閱 CryptMsgOpenToEncode的一節。

語法

BOOL CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

參數

[in] hKey

要用於解密之金鑰的句柄。應用程式會使用 CryptGenKey 或 CryptImportKey 函式來取得此句柄。

此金鑰會指定要使用的解密演算法。

[in] hHash

哈希物件的句柄。如果要同時解密和哈希數據，則會在此參數中傳遞哈希物件的句柄。哈希值會以解密的純文本更新。此選項在同時解密和驗證簽章時很有用。

呼叫 CryptDecrypt之前，應用程式必須藉由呼叫 CryptCreateHash 函式來取得哈希物件的句柄。解密完成之後，可以使用 CryptGetHashParam 函式來取得哈希值，也可以使用 cryptSignHash 函式來簽署，也可以使用 CryptVerifySignature 函式來驗證數位簽名。

如果未完成哈希，此參數必須是零。

[in] Final

布爾值，指定這是要解密的數列的最後一個區段。如果這是最後或唯一的區塊，則此值 TRUE。如果這不是最後一個區塊，這個值會 FALSE。如需詳細資訊，請參閱。

[in] dwFlags

定義下列旗標值。

價值	意義
CRYPT_OAEP 0x00000040	使用最佳非對稱加密填補（OAEP）（PKCS #1 第 2 版）。只有 RSA 加密/解密 Microsoft 增強式密碼編譯提供者才支援此旗標。這個旗標無法與 CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 旗標結合。
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	在 BLOB 上執行解密，而不檢查填補。只有 RSA 加密/解密 Microsoft 增強式密碼編譯提供者才支援此旗標。此旗標無法與 CRYPT_OAEP 旗標合併。

[in, out] pbData

緩衝區的指標，其中包含要解密的數據。執行解密之後，純文本會放回這個相同的緩衝區。

這個緩衝區中的加密位元組數目是由 pdwDataLen所指定。

[in, out] pdwDataLen

DWORD 值的指標，指出 pbData 緩衝區的長度。呼叫此函式之前，呼叫的應用程式會將 DWORD 值設定為要解密的位元組數目。傳回時，DWORD 值包含解密純文字的位元元組數目。

使用區塊加密時，除非這是要解密之數據的最後區段，否則此數據長度必須是區塊大小的倍數，而且 Final 參數 TRUE。

傳回值

如果函式成功，函式會傳回非零（TRUE）。

如果函式失敗，則會傳回零（FALSE）。如需擴充錯誤資訊，請呼叫 getLastError。

NTE 前面加上的錯誤碼是由所使用的特定 CSP 所產生。以下是一些可能的錯誤碼。

價值	描述
ERROR_INVALID_HANDLE	其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER	其中一個參數包含無效的值。這通常是無效的指標。
NTE_BAD_ALGID	hKey工作階段金鑰指定此 CSP 不支援的演算法。
NTE_BAD_DATA	要解密的數據無效。例如，使用區塊加密，且 Final 旗標 FALSE時，pdwDataLen 所指定的值必須是區塊大小的倍數。當找到填補無效時，也可以傳回此錯誤。
NTE_BAD_FLAGS	dwFlags 參數為非零。
NTE_BAD_HASH	hHash 參數包含無效的句柄。
NTE_BAD_KEY	hKey 參數不包含金鑰的有效句柄。
NTE_BAD_LEN	輸出緩衝區的大小太小，無法保存產生的純文本。
NTE_BAD_UID	找不到建立金鑰時指定的 CSP 內容。
NTE_DOUBLE_ENCRYPT	應用程式嘗試解密相同的數據兩次。
NTE_FAIL	函式以某種非預期的方式失敗。

言論

如果要解密大量數據，則可以在區段中重複呼叫 CryptDecrypt 來完成。只有在最後一次 呼叫 cryptDecrypt時，Final 參數必須設定為 TRUE，解密引擎才能正確完成解密程式。當最終TRUE時，會執行下列額外動作：

如果金鑰是區塊加密金鑰，數據會填補為加密的多個區塊大小。若要尋找加密的區塊大小，請使用 CryptGetKeyParam 來取得索引鍵的KP_BLOCKLEN值。
如果加密是以鏈結模式運作，則下一個 CryptDecrypt 作業會將加密的意見反應緩存器重設為密鑰的KP_IV值。
如果加密是數據流加密，則下一個 CryptDecrypt 呼叫會將加密重設為其初始狀態。

將加密的意見反應緩存器無法設定為索引鍵的KP_IV值，而不需將 Final 參數設定為 TRUE。如果這是必要的，就像您不想新增額外的填補區塊或變更每個區塊的大小一樣，您可以使用 CryptDuplicateKey 函式建立原始索引鍵的複本，並將重複的索引鍵傳遞至 cryptDecrypt 函式，以模擬此情況。這會導致原始索引鍵的KP_IV放在重複的索引鍵中。建立或匯入原始金鑰之後，您無法使用原始金鑰進行加密，因為密鑰的意見反應緩存器將會變更。下列虛擬程式代碼示範如何完成此作業。

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Microsoft 增強式密碼編譯提供者支援使用 RSA 公鑰進行直接加密，並以 RSA 私鑰進行解密。加密會使用 PKCS #1 填補。在解密時，會驗證此填補。加密文字要解密的數據長度必須與用來解密數據的 RSA 金鑰模數相同。如果加密文字在最重要的位元組中有零，這些位元組必須包含在輸入數據緩衝區和輸入緩衝區長度中。加密文字必須格式。

例子

如需使用此函式的範例，請參閱範例 C 程式：解密檔案。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	wincrypt.h
連結庫	Advapi32.lib
DLL	Advapi32.dll