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 または次の値を指定できます。

値 意味
BCRYPT_BLOCK_PADDING
 暗号化アルゴリズムでデータを次のブロック サイズに埋め込みます。 このフラグを指定しない場合、 cbInput パラメーターで指定されるプレーンテキストのサイズは、アルゴリズムのブロック サイズの倍数である必要があります。

ブロック サイズは、 BCryptGetProperty 関数を呼び出してキーの BCRYPT_BLOCK_LENGTH プロパティを取得することで取得できます。 これにより、アルゴリズムのブロックのサイズが提供されます。

このフラグは、認証された暗号化モード (AES-CCM および AES-GCM) では使用しないでください。
 

キーが非対称キーの場合は、次のいずれかの値を指定できます。

値 意味
BCRYPT_PAD_NONE
 パディングは使用しないでください。 pPaddingInfo パラメーターは使用されません。 cbInput パラメーターで指定するプレーンテキストのサイズは、アルゴリズムのブロック サイズの倍数である必要があります。
BCRYPT_PAD_OAEP
 最適非対称暗号化パディング (OAEP) スキームを使用します。 pPaddingInfo パラメーターは、BCRYPT_OAEP_PADDING_INFO構造体へのポインターです。
BCRYPT_PAD_PKCS1
 データには、ブロック サイズを丸めるために乱数が埋め込まれます。 pPaddingInfo パラメーターは使用されません。

戻り値

関数の成功または失敗を示す状態コードを返します。

可能なリターン コードには、次のものが含まれますが、これらに限定されません。

リターン コード 説明
STATUS_SUCCESS
 関数は成功しました。
STATUS_BUFFER_TOO_SMALL
 cbOutput パラメーターで指定されたサイズは、暗号テキストを保持するのに十分な大きさではありません。
STATUS_INVALID_BUFFER_SIZE
 cbInput パラメーターがアルゴリズムのブロック サイズの倍数ではなく、dwFlags パラメーターにBCRYPT_BLOCK_PADDINGまたはBCRYPT_PAD_NONE フラグが指定されていません。
STATUS_INVALID_HANDLE
 hKey パラメーターのキー ハンドルが無効です。
STATUS_INVALID_PARAMETER
 1 つ以上のパラメーターが無効です。
STATUS_NOT_SUPPORTED
 アルゴリズムは暗号化をサポートしていません。

注釈

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

こちらもご覧ください

BCryptDecrypt