CryptEncrypt 函式 (wincrypt.h)
支援 Secure/Multipurpose Internet Mail Extensions (S/MIME) 電子郵件互操作性的重要變更，已對影響信封郵件處理的 CryptoAPI 進行。 如需詳細資訊，請參閱 CryptMsgOpenToEncode 的一節。
語法
BOOL CryptEncrypt(
[in] HCRYPTKEY hKey,
[in] HCRYPTHASH hHash,
[in] BOOL Final,
[in] DWORD dwFlags,
[in, out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwBufLen
);
參數
[in] hKey
加密金鑰的句柄。 應用程式會使用 CryptGenKey 或 CryptImportKey 函式來取得此句柄。
金鑰會指定使用的加密演算法。
[in] hHash
哈希物件的句柄。 如果要同時哈希和加密數據，則可以在 hHash 參數中傳遞哈希物件的句柄。 哈希值會以傳入的 純文本 進行更新。 這個選項在產生已簽署和加密的文字時很有用。
呼叫 CryptEncrypt 之前，應用程式必須藉由呼叫 CryptCreateHash 函式來取得哈希物件的句柄。 加密完成後，可以使用 CryptGetHashParam 函式來取得哈希值，或使用 CryptSignHash 函式簽署哈希。
如果未完成哈希，這個參數必須是 NULL。
[in] Final
布爾值，指定這是否為加密數列中的最後一個區段。 最後 一個或唯一區塊的 Final 設定為 TRUE ;如果有更多區塊要加密，則設為 FALSE 。 如需詳細資訊，請參閱＜備註＞。
[in] dwFlags
已定義下列 dwFlags 值，但保留供日後使用。
| 值 | 意義 |
|---|---|
|
使用最佳非對稱加密填補 (OAEP) (PKCS #1 第 2 版) 。 只有具有 RSA 加密/解密的 Microsoft 增強式密碼編譯提供者 才支援此旗標。 |
[in, out] pbData
緩衝區的指標，其中包含要加密的純文本。 此緩衝區中的純文本會以此函式所建立的 加密文字 覆寫。
pdwDataLen 參數指向包含純文本長度的變數，以位元組為單位。 dwBufLen 參數包含這個緩衝區的總大小，以位元組為單位。
如果此參數包含 NULL，此函式會計算加密文字的必要大小，並將它放在 pdwDataLen 參數所指向的值中。
[in, out] pdwDataLen
在專案上， DWORD 值的指標包含 pbData 緩衝區中純文字的長度，以位元組為單位。 結束時，這個 DWORD 包含寫入 pbData 緩衝區之加密文字的長度，以位元組為單位。
如果為 pbData 配置的緩衝區不夠大，無法保存加密的數據，GetLastError 會傳回ERROR_MORE_DATA，並以位元組為單位儲存 pdwDataLen 所指向的 DWORD 值所需的緩衝區大小。
如果 pbData 為 NULL，則不會傳回任何錯誤，而且函式會將加密數據的大小儲存在 pdwDataLen 所指向的 DWORD 值中，以位元組為單位。 這可讓應用程式判斷正確的緩衝區大小。
使用 區塊加密 時，除非這是要加密之數據的最後一個區段，而且 Final 參數為 TRUE，否則此數據長度必須是區塊大小的倍數。
[in] dwBufLen
指定輸入 pbData 緩衝區的大小總計，以位元組為單位。
請注意，根據所使用的演算法，加密的文字可以大於原始純文本。 在此情況下， pbData 緩衝區必須夠大，才能包含加密的文字和任何邊框間距。
規則是，如果使用 數據流加密 ，則加密文字的大小與純文本相同。 如果使用 區塊加密 ，則加密文字最多為大於純文本的區塊長度。
傳回值
如果函式成功，函式會傳回非零 (TRUE) 。
如果函式失敗，它會傳回零 (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError。
NTE 前面出現的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。
| 值 | Description |
|---|---|
|
其中一個參數指定無效的句柄。 |
|
其中一個參數包含無效的值。 這通常是無效的指標。 |
|
hKey會話密鑰指定此 CSP 不支援的演算法。 |
|
要加密的數據無效。 例如，使用區塊加密且 [最終 ] 旗標為 FALSE 時， pdwDataLen 所指定的值必須是區塊大小的倍數。 |
|
dwFlags 參數為非零。 |
|
hHash 參數包含無效的句柄。 |
|
嘗試將數據新增至已標示為「已完成」的哈希物件。 |
|
hKey 參數不包含密鑰的有效句柄。 |
|
輸出緩衝區的大小太小，無法保存產生的加密文字。 |
|
找不到建立金鑰時指定的 CSP 內容。 |
|
應用程式嘗試加密相同的數據兩次。 |
|
函式以非預期的方式失敗。 |
|
CSP 在作業期間記憶體不足。 |
備註
如果要加密大量數據，則可以在區段中重複呼叫 CryptEncrypt 來完成。 最後一次呼叫 CryptEncrypt 時，Final 參數必須設定為 TRUE，以便加密引擎可以正確完成加密程式。 當 Final 為 TRUE 時，會執行下列額外動作：
- 如果金鑰是區塊加密金鑰，數據會填補到加密的多個區塊大小。 如果數據長度等於加密的區塊大小，則會將一個額外的填補區塊附加至數據。 若要尋找加密的區塊大小，請使用 CryptGetKeyParam 來取得索引鍵的KP_BLOCKLEN值。
- 如果加密是以 鏈結模式運作，下一個 CryptEncrypt 作業會將加密的意見反應緩存器重設為密鑰的KP_IV值。
- 如果加密是 數據流加密，下一個 CryptEncrypt 會將加密重設為其初始 狀態。
沒有辦法將加密的意見反應註冊為索引鍵的KP_IV值，而不將 Final 參數設定為 TRUE。 如果需要這樣做，如同您不想新增額外的填補區塊或變更每個區塊的大小，您可以使用 CryptDuplicateKey 函式建立原始密鑰的複本，並將重複的索引鍵傳遞至 CryptEncrypt 函式來模擬。 這會導致原始索引鍵的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)
// Encrypt the block with the duplicate key.
CryptEncrypt(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 金鑰呼叫 CryptEncrypt 來加密的純文字數據長度是金鑰模數減十一個字節的長度。 第十一個字節是 PKCS #1 填補選擇的最小值。 加密文字會以 小端 格式傳回。
範例
如需使用此函式的範例，請參閱 範例 C 程式：加密檔案 和 範例 C 程式：解密檔案。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wincrypt.h |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應