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

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

戻り値

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

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

注釈

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 を使用します。

要件

こちらもご覧ください

BCryptDecrypt