EncryptMessage 関数 (sspi.h)

[アーティクル]
03/08/2023

EncryptMessage (Digest) 関数は、プライバシーを提供するためにメッセージを暗号化します。 EncryptMessage (Digest) を使用すると、選択したメカニズムでサポートされている暗号化アルゴリズムの中からアプリケーションを選択できます。 EncryptMessage (Digest) 関数は、コンテキストハンドルによって参照されるセキュリティコンテキストを使用します。一部のパッケージには、暗号化または暗号化解除するメッセージはなく、チェックできる整合性ハッシュが提供されます。

この関数は、SASL メカニズムとしてのみ使用できます。

注 EncryptMessage(Digest) と DecryptMessage (Digest) は、1 つのスレッドが暗号化されていて、もう一方のスレッドが暗号化解除されている場合、1 つのセキュリティサポートプロバイダーインターフェイス (SSPI) コンテキストの 2 つの異なるスレッドから同時に呼び出すことができます。複数のスレッドが暗号化されている場合、または複数のスレッドが暗号化を解除している場合、各スレッドは一意のコンテキストを取得する必要があります。

構文

SECURITY_STATUS SEC_ENTRY EncryptMessage(
  [in]      PCtxtHandle    phContext,
  [in]      unsigned long  fQOP,
  [in, out] PSecBufferDesc pMessage,
  [in]      unsigned long  MessageSeqNo
);

パラメーター

[in] phContext

メッセージの暗号化に使用されるセキュリティコンテキストへのハンドル。

[in] fQOP

保護の品質を示すパッケージ固有のフラグ。セキュリティパッケージでは、このパラメーターを使用して暗号化アルゴリズムの選択を有効にすることができます。

Digest SSP を使用する場合、このパラメーターは 0 に設定する必要があります。

[in, out] pMessage

SecBufferDesc 構造体へのポインター。入力時に、構造体は、SECBUFFER_DATA型の 1 つ以上の SecBuffer 構造体を参照します。そのバッファーには、暗号化するメッセージが含まれています。メッセージは暗号化され、構造体の元の内容が上書きされます。

関数は、SECBUFFER_READONLY属性を使用してバッファーを処理しません。

メッセージを含む SecBuffer 構造体の長さは、QueryContextAttributes (Digest) (SECPKG_ATTR_STREAM_SIZES) 関数から取得される cbMaximumMessage を超えてはなりません。

Digest SSP を使用する場合、署名情報を保持するには、SECBUFFER_PADDING型またはSEC_BUFFER_DATAの 2 番目のバッファーが必要です。出力バッファーのサイズを取得するには、 QueryContextAttributes (Digest) 関数を呼び出し、SECPKG_ATTR_SIZESを指定します。関数は、SecPkgContext_Sizes 構造体を返します。出力バッファーのサイズは、 cbMaxSignature メンバーと cbBlockSize メンバーの値の合計です。

SSL を使用しないアプリケーションでは、SECBUFFER_PADDING型の SecBuffer を指定する必要があります。

[in] MessageSeqNo

トランスポートアプリケーションがメッセージに割り当てたシーケンス番号。トランスポートアプリケーションがシーケンス番号を保持しない場合、このパラメーターは 0 である必要があります。

Digest SSP を使用する場合、このパラメーターは 0 に設定する必要があります。ダイジェスト SSP は、シーケンスの番号付けを内部的に管理します。

戻り値

関数が成功した場合、関数はSEC_E_OKを返します。

関数が失敗すると、次のいずれかのエラーコードが返されます。

リターンコード	説明
SEC_E_BUFFER_TOO_SMALL	出力バッファーが小さすぎます。詳細については、「解説」を参照してください。
SEC_E_CONTEXT_EXPIRED	アプリケーションは、既に閉じられているコンテキストを参照しています。適切に記述されたアプリケーションでは、このエラーを受け取るべきではありません。
SEC_E_CRYPTO_SYSTEM_INVALID	セキュリティコンテキストに対して選択された暗号はサポートされていません。
SEC_E_INSUFFICIENT_MEMORY	要求されたアクションを完了するのに十分なメモリがありません。
SEC_E_INVALID_HANDLE	無効なコンテキストハンドルが phContext パラメーターで指定されました。
SEC_E_INVALID_TOKEN	SECBUFFER_DATA型バッファーが見つかりませんでした。
SEC_E_QOP_NOT_SUPPORTED	機密性も整合性も、セキュリティコンテキストではサポートされていません。

解説

EncryptMessage (Digest) 関数は、メッセージとセキュリティコンテキストからのセッションキーに基づいてメッセージを暗号化します。

トランスポートアプリケーションがシーケンス検出をサポートするセキュリティコンテキストを作成し、呼び出し元がシーケンス番号を指定した場合、関数には暗号化されたメッセージにこの情報が含まれます。この情報を含めると、メッセージの再生、挿入、抑制から保護されます。セキュリティパッケージには、トランスポートアプリケーションから渡されたシーケンス番号が組み込まれています。

Digest SSP を使用する場合は、 QueryContextAttributes (Digest) 関数を呼び出し、SECPKG_ATTR_SIZESを指定して、出力バッファーのサイズを取得します。関数は、SecPkgContext_Sizes 構造体を返します。出力バッファーのサイズは、 cbMaxSignature メンバーと cbBlockSize メンバーの値の合計です。

メモこれらのバッファーは、示されている順序で指定する必要があります。

バッファーの種類	説明
SECBUFFER_STREAM_HEADER	内部使用。初期化は必要ありません。
SECBUFFER_DATA	暗号化するプレーンテキストメッセージを格納します。
SECBUFFER_STREAM_TRAILER	内部使用。初期化は必要ありません。
SECBUFFER_EMPTY	内部使用。初期化は必要ありません。サイズは 0 にすることができます。

最適なパフォーマンスを得るための pMessage 構造体は、連続するメモリから割り当てる必要があります。

Windows XP: この関数は SealMessage とも呼ばれていました。アプリケーションでは EncryptMessage (Digest) のみを使用する必要があります。

要件


サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	sspi.h (Security.h を含む)
Library	Secur32.lib
[DLL]	Secur32.dll

次の方法で共有

EncryptMessage 関数 (sspi.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース