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
呼叫 CryptEncrypt之前，應用程式必須藉由呼叫 CryptCreateHash 函式來取得哈希物件的句柄。 加密完成之後，可以使用 cryptGetHashParam 函式
如果未完成哈希，此參數必須 NULL。
[in] 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 值。
如果 pbDataNULL，則不會傳回錯誤，而且函式會將加密數據的大小以位元組為單位儲存在 pdwDataLen所指向的 DWORD 值。 這可讓應用程式判斷正確的緩衝區大小。
使用 區塊加密 時，除非這是要加密之數據的最後區段，否則此數據長度必須是區塊大小的倍數，而且 Final 參數 TRUE。
[in] dwBufLen
指定輸入 pbData 緩衝區的大小總計，以位元組為單位。
請注意，根據所使用的演算法，加密的文字可以大於原始純文本。 在此情況下，pbData 緩衝區必須夠大，才能包含加密的文字和任何填補。
規則是，如果使用 數據流加密，則加密文字的大小與純文本相同。 如果使用 區塊加密，則加密文字長度會大於純文本。
傳回值
如果函式成功，函式會傳回非零 （TRUE）。
如果函式失敗，則會傳回零 （FALSE）。 如需擴充錯誤資訊，請呼叫 getLastError
NTE 前面加上的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。
| 價值 | 描述 |
|---|---|
|
其中一個參數指定無效的句柄。 |
|
其中一個參數包含無效的值。 這通常是無效的指標。 |
|
hKey工作階段金鑰 指定此 CSP 不支援的演算法。 |
|
要加密的數據無效。 例如，使用區塊加密，且 Final 旗標 FALSE時，pdwDataLen 所指定的值必須是區塊大小的倍數。 |
|
dwFlags 參數為非零。 |
|
hHash 參數包含無效的句柄。 |
|
嘗試將數據新增至已標示為「已完成」的哈希物件。 |
|
hKey 參數不包含金鑰的有效句柄。 |
|
輸出緩衝區的大小太小，無法保存產生的加密文字。 |
|
找不到建立金鑰時指定的 CSP 內容。 |
|
應用程式嘗試加密相同的數據兩次。 |
|
函式以某種非預期的方式失敗。 |
|
CSP 在作業期間記憶體不足。 |
言論
如果要加密大量數據，則可以在區段中重複呼叫 CryptEncrypt 來完成。 最後一次 呼叫 cryptEncrypt時，Final 參數必須設定為 TRUE，讓加密引擎可以正確完成加密程式。 當 最終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 可以加密的純文字數據長度是金鑰模數減去 11 個字節的長度。 11 個字節是 PKCS #1 填補選擇的最小值。 加密文字會以 格式傳回。
例子
如需使用此函式的範例，請參閱 範例 C 程式：加密檔案 和 範例 C 程式：解密檔案。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | wincrypt.h |
| 連結庫 | Advapi32.lib |
| DLL | Advapi32.dll |