CryptEncrypt 関数 (wincrypt.h)
Secure/多目的インターネット メール拡張機能 (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
エントリ上の、pbData バッファー内のプレーンテキストの長さをバイト単位で格納する DWORD 値へのポインター。 終了時に、この DWORD には 、pbData バッファーに書き込まれた暗号テキストの長さ (バイト単位) が含まれます。
pbData に割り当てられたバッファーが暗号化されたデータを保持するのに十分な大きさでない場合、GetLastError はERROR_MORE_DATAを返し、pdwDataLen が指す DWORD 値に必要なバッファー サイズをバイト単位で格納します。
pbData が NULL の場合、エラーは返されません。関数は、暗号化されたデータのサイズをバイト単位で pdwDataLen が指す DWORD 値に格納します。 これにより、アプリケーションは正しいバッファー サイズを決定できます。
ブロック暗号を使用する場合、暗号化するデータの最後のセクションで Final パラメーターが TRUE でない限り、このデータ長はブロック サイズの倍数である必要があります。
[in] dwBufLen
入力 pbData バッファーの合計サイズをバイト単位で指定します。
使用されるアルゴリズムによっては、暗号化されたテキストが元のプレーンテキストよりも大きくなる場合があることに注意してください。 この場合、 pbData バッファーは、暗号化されたテキストとパディングを格納するのに十分な大きさにする必要があります。
原則として、 ストリーム暗号 が使用される場合、暗号テキストはプレーンテキストと同じサイズになります。 ブロック暗号を使用する場合、暗号テキストはプレーンテキストより大きいブロック長までになります。
戻り値
関数が成功した場合、関数は 0 以外 (TRUE) を返します。
関数が失敗した場合は、0 (FALSE) を返します。 拡張エラー情報については、 GetLastError を呼び出します。
NTE の前のエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。
| 値 | 説明 |
|---|---|
|
パラメーターの 1 つは、無効なハンドルを指定します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。 |
|
hKeyセッション キーは、この CSP がサポートしていないアルゴリズムを指定します。 |
|
暗号化するデータが無効です。 たとえば、ブロック暗号が使用され、 Final フラグが FALSE の場合、 pdwDataLen で指定される値はブロック サイズの倍数である必要があります。 |
|
dwFlags パラメーターは 0 以外です。 |
|
hHash パラメーターには、無効なハンドルが含まれています。 |
|
既に "完了" とマークされているハッシュ オブジェクトにデータを追加しようとしました。 |
|
hKey パラメーターには、キーへの有効なハンドルが含まれていません。 |
|
出力バッファーのサイズが小さすぎて、生成された暗号テキストを保持できません。 |
|
キーの作成時に指定された CSP コンテキストが見つかりません。 |
|
アプリケーションが同じデータを 2 回暗号化しようとしました。 |
|
関数が予期しない方法で失敗しました。 |
|
操作中に CSP のメモリが不足しました。 |
注釈
大量のデータを暗号化する場合は、 セクションで CryptEncrypt を繰り返し呼び出すことで行うことができます。 最終パラメーターは、暗号化エンジンが暗号化プロセスを適切に完了できるように、CryptEncrypt の最後の呼び出しで TRUE に設定する必要があります。 Final が TRUE の場合は、次の追加アクションが実行されます。
- キーがブロック暗号キーの場合、データは暗号のブロック サイズの倍数に埋め込まれます。 データ長が暗号のブロック サイズと等しい場合は、1 つの追加の埋め込みブロックがデータに追加されます。 暗号のブロック サイズを見つけるには、 CryptGetKeyParam を使用してキーのKP_BLOCKLEN値を取得します。
- 暗号が チェーン モードで動作している場合、次の CryptEncrypt 操作により、暗号のフィードバック レジスタがキーのKP_IV値にリセットされます。
- 暗号が ストリーム暗号の場合、次の CryptEncrypt は暗号 を初期状態にリセットします。
Final パラメーターを TRUE に設定せずに、暗号のフィードバック レジスタをキーのKP_IV値に設定する方法はありません。 必要に応じて、追加の埋め込みブロックを追加したり、各ブロックのサイズを変更したりしない場合と同様に、 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 Enhanced Cryptographic Provider では、RSA公開キーを使用した直接暗号化と RSA 秘密キーによる暗号化解除がサポートされています。 暗号化では PKCS #1 パディングが使用されます。 復号化時に、このパディングが検証されます。 RSA キーを使用して CryptEncrypt を呼び出して暗号化できるプレーンテキスト データの長さは、キーの剰余から 11 バイトを引いた長さです。 PKCS #1 のパディングで選択された最小値は 11 バイトです。 暗号テキストは リトル エンディアン 形式で返されます。
例
この関数を使用する例については、「 サンプル C プログラム: ファイルの暗号化」 および「 サンプル C プログラム: ファイルの暗号化解除」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示