AcceptSecurityContext (Schannel) 関数

  • [アーティクル]

AcceptSecurityContext (Schannel) 関数を使用すると、トランスポート アプリケーションのサーバー コンポーネントで、サーバーとリモート クライアントの間にセキュリティ コンテキストを確立できます。 リモート クライアントは InitializeSecurityContext (Schannel) 関数を使用して 、セキュリティ コンテキストを確立するプロセスを開始します。 サーバーは、 セキュリティ コンテキストの確立を完了するために、リモート クライアントから 1 つ以上の応答トークンを要求できます。

構文

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

パラメーター

phCredential[in, optional]

サーバーの資格情報のハンドル。 サーバーは、このハンドルを取得するために SECPKG_CRED_INBOUND または SECPKG_CRED_BOTH フラグを設定して AcquireCredentialsHandle (Schannel) 関数を呼び出します。

phContext[in, out, optional]

CtxtHandle 構造体へのポインター。 AcceptSecurityContext (Schannel) の最初の呼び出しでは、このポインターは ですNULL。 後続の呼び出しでは、 phContext は、最初の呼び出しによって phNewContext パラメーターで返された部分的に形成されたコンテキストへのハンドルです。

警告

AcceptSecurityContext (Schannel) の同時呼び出しでは、同じコンテキスト ハンドルを使用しないでください。 セキュリティ サービス プロバイダーの API 実装はスレッド セーフではありません。

pInput[in, optional]

入力バッファー記述子を含む InitializeSecurityContext (Schannel) のクライアント呼び出しによって生成される SecBufferDesc 構造体へのポインター。

Schannel セキュリティ サポート プロバイダー (SSP) を使用する場合、最初のバッファーは SECBUFFER_TOKEN 型で、クライアントから受信したセキュリティ トークンを含む必要があります。 2 番目のバッファーは、SECBUFFER_EMPTY型である必要があります。

fContextReq[in]

サーバーがコンテキストを確立するために必要な属性を指定するビット フラグ。 ビット フラグは、ビットごとの OR 演算を使用して組み合わせることができます。 このパラメーターには、次の値の 1 つ以上を指定できます。

値 意味
ASC_REQ_ALLOCATE_MEMORY ダイジェストと Schannel によって出力バッファーが割り当てられます。 出力バッファーの使用が完了したら、 FreeContextBuffer 関数を呼び出して解放します。
ASC_REQ_CONFIDENTIALITY メッセージの暗号化と暗号化解除。
Digest SSP では、SASL に対してのみこのフラグがサポートされます。
ASC_REQ_CONNECTION セキュリティ コンテキストでは、書式設定メッセージは処理されません。
ASC_REQ_EXTENDED_ERROR エラーが発生すると、リモート パーティに通知されます。
ASC_REQ_MUTUAL_AUTH クライアントは、クライアント認証に使用する証明書を指定する必要があります。
ASC_REQ_REPLAY_DETECT 再生されたパケットを検出します。
ASC_REQ_SEQUENCE_DETECT 受信したメッセージを順番に検出します。
ASC_REQ_STREAM ストリーム指向の接続をサポートします。
このフラグは、Schannel でのみサポートされています。

可能な属性フラグとその意味については、「 コンテキスト要件」を参照してください。 このパラメーターに使用されるフラグには、ASC_REQ (たとえば、ASC_REQ_DELEGATE) がプレフィックスとして付けられます。

要求された属性は、クライアントでサポートされていない可能性があります。 詳細については、 pfContextAttr パラメーターを参照してください。

TargetDataRep[in]

このパラメーターは Schannel では使用されません。 このパラメーターには 0 を指定します。

phNewContext[in, out, optional]

CtxtHandle 構造体へのポインター。 AcceptSecurityContext (Schannel) の最初の呼び出しで、このポインターは新しいコンテキスト ハンドルを受け取ります。 後続の呼び出しでは、 phNewContext は phContext パラメーターで指定されたハンドルと同じにすることができます。 phNewContext を に NULLしないでください。

pOutput[in, out, optional]

出力バッファー記述子を含む SecBufferDesc 構造体へのポインター。 このバッファーは、 InitializeSecurityContext (Schannel) への追加の呼び出しへの入力のためにクライアントに送信されます。 関数がSEC_E_OKを返した場合でも、出力バッファーが生成される場合があります。 生成されたバッファーは、クライアント アプリケーションに返送する必要があります。

出力時に、このバッファーは セキュリティ コンテキストのトークンを受け取ります。 トークンはクライアントに送信する必要があります。 関数は、SECBUFFER_EXTRA型のバッファーを返すこともできます。 さらに、呼び出し元は SECBUFFER_ALERT 型のバッファーを渡す必要があります。 出力時に、アラートが生成された場合、このバッファーにはそのアラートに関する情報が含まれており、関数は失敗します。

pfContextAttr[out]

確立されたコンテキストの属性を示すビット フラグのセットを受け取る変数へのポインター。 さまざまな属性の説明については、「 コンテキスト要件」を参照してください。 このパラメーターに使用されるフラグには、ASC_RET_DELEGATEなど、ASC_RETがプレフィックスとして付けられます。

最終的な関数呼び出しが正常に返されるまで、セキュリティ関連の属性をチェックしないでください。 セキュリティに関連しない属性フラグ (ASC_RET_ALLOCATED_MEMORY フラグなど) は、最終的な戻り値の前に確認できます。

ptsTimeStamp[out, optional]

コンテキストの有効期限を受け取る TimeStamp 構造体へのポインター。 セキュリティ パッケージでは、常にローカル時刻にこの値を返すようにお勧めします。

これは、Schannel SSP を使用する場合は省略可能です。 リモート パーティが認証に使用する証明書を指定すると、このパラメーターはその証明書の有効期限を受け取ります。 証明書が指定されていない場合は、最大時間値が返されます。

注意

認証プロセスの最後の呼び出しまで、ネゴシエーションの後の段階で詳細情報が提供されるため、コンテキストの有効期限が正しくない可能性があります。 したがって、 ptsTimeStamp は、関数の最後の呼び出しまでである NULL 必要があります。

戻り値

この関数は、次のいずれかの値を返します。

リターン コード/値説明
SEC_E_INCOMPLETE_MESSAGE
0x80090318L
関数が正常に実行されました。 入力バッファー内のデータが不完全です。 アプリケーションは、クライアントから追加のデータを読み取り、[AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) をもう一度呼び出す必要があります。
この値が返されると、pInput バッファーには、BufferType メンバーが SECBUFFER_MISSING の [SecBuffer](/windows/win32/api/sspi/ns-sspi-secbuffer) 構造体が含まれます。 SecBuffer の cbBuffer メンバーには、この関数が成功する前に関数がクライアントから読み取る必要がある追加バイト数を示す値が含まれています。 この数値は常に正確であるとは限りませんが、使用すると、この関数の複数の呼び出しを回避することでパフォーマンスを向上させることができます。
SEC_E_INSUFFICIENT_MEMORY
0x80090300L
関数が失敗しました。 要求されたアクションを完了するのに十分なメモリがありません。
SEC_E_INTERNAL_ERROR
0x80090304L
関数が失敗しました。 SSPI エラー コードにマップされないエラーが発生しました。
SEC_E_INVALID_HANDLE
0x80100003L
関数が失敗しました。 関数に渡されたハンドルが無効です。
SEC_E_INVALID_TOKEN
0x80090308L
関数が失敗しました。 関数に渡されたトークンが無効です。
SEC_E_LOGON_DENIED
0x8009030CL
ログオンに失敗しました。
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L
関数が失敗しました。 認証のために機関に連絡できませんでした。 これは、次の条件が原因である可能性があります。
  • 認証側のドメイン名が正しくありません。
  • ドメインは使用できません。
  • 信頼関係が失敗しました。
SEC_E_NO_CREDENTIALS
0x8009030EL
関数が失敗しました。 phCredential パラメーターで指定された資格情報ハンドルが無効です。 この値は、Digest または Schannel SSP を使用する場合に返すことができます。
SEC_E_OK
0x000000000L
関数が正常に実行されました。 [*セキュリティ コンテキスト*](..クライアントから受信した /secgloss/s-gly.md) が受け入れられました。 関数によって出力トークンが生成された場合は、クライアント プロセスに送信する必要があります。
SEC_E_UNSUPPORTED_FUNCTION
0x80090302L
関数が失敗しました。 fContextReq パラメーターで無効なコンテキスト属性フラグ (ASC_REQ_DELEGATEまたはASC_REQ_PROMPT_FOR_CREDS) が指定されました。
SEC_E_APPLICATION_PROTOCOL_MISMATCH
0x80090367L
クライアントとサーバーの間に共通のアプリケーション プロトコルが存在しません。
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L
関数が正常に実行されました。 サーバーは [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) を呼び出し、出力トークンをクライアントに渡す必要があります。 次に、サーバーはクライアントからのリターン トークンを待機し、[AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) を別の呼び出しで呼び出します。
SEC_I_COMPLETE_NEEDED
0x00090313L
関数が正常に実行されました。 サーバーは、クライアントからのメッセージの作成を完了し、[CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) 関数を呼び出す必要があります。
SEC_I_CONTINUE_NEEDED
0x00090312L
関数が正常に実行されました。 サーバーは出力トークンをクライアントに送信し、返されたトークンを待機する必要があります。 [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) の別の呼び出しに対して、返されたトークンを pInput に渡す必要があります。
STATUS_LOGON_FAILURE
0xC000006DL
関数が失敗しました。 [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) 関数は、指定したコンテキストが確立された後に呼び出されました。 この値は、Digest SSP を使用するときに返すことができます。

解説

AcceptSecurityContext (Schannel) 関数は、InitializeSecurityContext (Schannel) 関数に対応するサーバーです。

サーバーがクライアントから要求を受信すると、サーバーは fContextReq パラメーターを使用してセッションに必要なものを指定します。 この方法では、サーバーは、クライアントが機密または 整合性チェックされたセッションを使用できる必要があることを指定でき、その要求を満たすことができないクライアントを拒否できます。 または、サーバーに何も必要とされず、クライアントが提供できる内容または必要なものは、 pfContextAttr パラメーターで返されます。

相互認証などの複数区間認証をサポートするパッケージの場合、呼び出しシーケンスは次のようになります。

  1. クライアントは、トークンをサーバーに送信します。
  2. サーバーは AcceptSecurityContext (Schannel) を初めて呼び出し、クライアントに送信される応答トークンを生成します。
  3. クライアントはトークンを受け取り、 InitializeSecurityContext (Schannel) に渡します。 InitializeSecurityContext (Schannel) がSEC_E_OKを返した場合、相互認証が完了し、セキュリティで保護されたセッションを開始できます。 InitializeSecurityContext (Schannel) がエラー コードを返した場合、相互認証ネゴシエーションは終了します。 それ以外の場合は、 InitializeSecurityContext (Schannel) によって返されるセキュリティ トークンがクライアントに送信され、手順 2 と 3 が繰り返されます。
  4. AcceptSecurityContext (Schannel) の同時呼び出しでは phContext 値を使用しないでください。 セキュリティ プロバイダーの実装はスレッド セーフではありません。

fContextReq パラメーターと pfContextAttr パラメーターは、さまざまなコンテキスト属性を表すビットマスクです。 さまざまな属性の説明については、「 コンテキスト要件」を参照してください。

注意

pfContextAttr パラメーターは、正常に返された場合は有効ですが、最終的に正常に返された場合にのみ、コンテキストのセキュリティの側面に関連するフラグを調べる必要があります。 中間の戻り値は、たとえば、ISC_RET_ALLOCATED_MEMORY フラグを設定できます。

呼び出し元は、最終的なコンテキスト属性で十分かどうかを判断する責任があります。 たとえば、機密性 (暗号化) が要求されたが、確立できなかった場合、一部のアプリケーションは接続を直ちにシャットダウンすることを選択できます。 セキュリティ コンテキストを確立できない場合、サーバーは DeleteSecurityContext 関数を呼び出して、部分的に作成されたコンテキストを解放する必要があります。 DeleteSecurityContext 関数を呼び出すタイミングについては、「DeleteSecurityContext」を参照してください。

セキュリティ コンテキストが確立されると、サーバー アプリケーションは QuerySecurityContextToken 関数を使用して、クライアント証明書がマップされたユーザー アカウントへのハンドルを取得できます。 また、サーバーは ImpersonateSecurityContext 関数を使用してユーザーを偽装できます。

要件

要件 値
サポートされている最小のクライアント Windows 8.1 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2012 R2 [デスクトップ アプリのみ]
Header Sspi.h (Security.h を含む)
ライブラリ Secur32.lib
[DLL] Secur32.dll

こちらもご覧ください

SSPI 関数

DeleteSecurityContext

InitializeSecurityContext (Schannel)