BCryptEncrypt 関数 (bcrypt.h)
BCryptEncrypt 関数は、データブロックを暗号化します。
構文
NTSTATUS BCryptEncrypt(
[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 にすることができます 。
IV の必要なサイズは、 BCryptGetProperty 関数を呼び出して BCRYPT_BLOCK_LENGTH プロパティを取得することで取得できます。 これにより、アルゴリズムのブロックのサイズが提供されます。これは IV のサイズでもあります。
[in] cbIV
pbIV バッファーのサイズ (バイト単位)。
[out, optional] pbOutput
この関数によって生成される 暗号テキスト を受け取るバッファーのアドレス。 cbOutput パラメーターには、このバッファーのサイズが含まれています。 詳細については、「解説」を参照してください。
このパラメーターが NULL の場合、 BCryptEncrypt 関数は pbInput パラメーターで渡されるデータの暗号テキストに必要なサイズを計算します。 この場合、 pcbResult パラメーターが指す場所にはこのサイズが含まれており、関数は STATUS_SUCCESSを返します。 pPaddingInfo パラメーターは変更されません。
pbOutput パラメーターと pbInput パラメーターの両方の値が NULL の場合、認証された暗号化アルゴリズムが使用されていない限り、エラーが返されます。 後者の場合、呼び出しは長さ 0 のデータを含む認証された暗号化呼び出しとして扱われ、認証タグは pPaddingInfo パラメーターで返されます。
[in] cbOutput
pbOutput バッファーのサイズ (バイト単位)。 pbOutput パラメーターが NULL の場合、このパラメーターは無視されます。
[out] pcbResult
pbOutput バッファーにコピーされたバイト数を受け取る ULONG 変数へのポインター。 pbOutput が NULL の場合、暗号テキストに必要なサイズ (バイト単位) を受け取ります。
[in] dwFlags
この関数の動作を変更するフラグのセット。 許可されるフラグのセットは、 hKey パラメーターで指定されたキーの種類によって異なります。
キーが対称キーの場合は、0 または次の値を指定できます。
| 値 | 意味 |
|---|---|
|
暗号化アルゴリズムでデータを次のブロック サイズに埋め込みます。 このフラグを指定しない場合、 cbInput パラメーターで指定されるプレーンテキストのサイズは、アルゴリズムのブロック サイズの倍数である必要があります。
ブロック サイズは、 BCryptGetProperty 関数を呼び出してキーの BCRYPT_BLOCK_LENGTH プロパティを取得することで取得できます。 これにより、アルゴリズムのブロックのサイズが提供されます。 このフラグは、認証された暗号化モード (AES-CCM および AES-GCM) では使用しないでください。 |
キーが非対称キーの場合は、次のいずれかの値を指定できます。
| 値 | 意味 |
|---|---|
|
パディングは使用しないでください。 pPaddingInfo パラメーターは使用されません。 cbInput パラメーターで指定するプレーンテキストのサイズは、アルゴリズムのブロック サイズの倍数である必要があります。 |
|
最適非対称暗号化パディング (OAEP) スキームを使用します。 pPaddingInfo パラメーターは、BCRYPT_OAEP_PADDING_INFO構造体へのポインターです。 |
|
データには、ブロック サイズを丸めるために乱数が埋め込まれます。 pPaddingInfo パラメーターは使用されません。 |
戻り値
関数の成功または失敗を示す状態コードを返します。
可能なリターン コードには、次のものが含まれますが、これらに限定されません。
| リターン コード | 説明 |
|---|---|
|
関数は成功しました。 |
|
cbOutput パラメーターで指定されたサイズは、暗号テキストを保持するのに十分な大きさではありません。 |
|
cbInput パラメーターがアルゴリズムのブロック サイズの倍数ではなく、dwFlags パラメーターにBCRYPT_BLOCK_PADDINGまたはBCRYPT_PAD_NONE フラグが指定されていません。 |
|
hKey パラメーターのキー ハンドルが無効です。 |
|
1 つ以上のパラメーターが無効です。 |
|
アルゴリズムは暗号化をサポートしていません。 |
注釈
pbInput パラメーターと pbOutput パラメーターは等しい場合があります。 この場合、この関数は暗号化を実行します。 暗号化されたデータ サイズが暗号化されていないデータ サイズよりも大きくなる可能性があるため、バッファーは暗号化されたデータを保持するのに十分な大きさにする必要があります。 pbInput と pbOutput が等しくない場合、2 つのバッファーが重複しない可能性があります。
プロバイダーがサポートするプロセッサ モードに応じて、 BCryptEncrypt はユーザー モードまたはカーネル モードから呼び出すことができます。 カーネル モードの呼び出し元は、PASSIVE_LEVEL IRQL または IRQL DISPATCH_LEVELで実行できます。 現在の IRQL レベルが DISPATCH_LEVELされている場合、 hKey パラメーターに指定されたハンドルは、 BCRYPT_PROV_DISPATCH フラグで開かれたプロバイダーによって返されるアルゴリズム ハンドルから派生する必要があります。 また、BCryptEncrypt 関数に渡されるすべてのポインターは、非ページ (またはロックされた) メモリを参照する必要があります。
カーネル モードでこの関数を呼び出すには、ドライバー開発キット (DDK) の一部である Cng.lib を使用します。 Windows Server 2008 と Windows Vista: カーネル モードでこの関数を呼び出すには、Ksecdd.lib を使用します。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | bcrypt.h |
| Library | Bcrypt.lib |
| [DLL] | Bcrypt.dll |