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 パラメータで返された、部分的に形成されたコンテキストへのハンドルです。

pInput[in, optional]

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

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

fContextReq[in]

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

可能な属性フラグとその意味については、 コンテキスト要件を参照してください。 このパラメータに使用されるフラグには、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 というプレフィックスが付きます (例: ASC_RET_DELEGATE)。

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

ptsTimeStamp[out, optional]

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

これは、Schannel 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 パラメータは、さまざまなコンテキスト属性を表すビットマスクです。 さまざまな属性の説明については、「コンテキスト要件」を参照してください。

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

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

必要条件

こちらもご覧ください

SSPI 関数

DeleteSecurityContext

InitializeSecurityContext (Schannel)