InitializeSecurityContext (General) 関数

InitializeSecurityContext (General) 関数は、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。 この関数は、クライアント アプリケーションとリモート ピアの間にセキュリティ コンテキストを構築するために使用されます。 InitializeSecurityContext (General) は、クライアントがリモート ピアに渡す必要があるトークンを返し、ピアは AcceptSecurityContext (General) 呼び出しを通じてローカル セキュリティ実装に順番に送信します。 生成されるトークンは、すべての呼び出し元から不透明と見なされる必要があります。

通常、InitializeSecurityContext (General) 関数は、十分なセキュリティ コンテキストが確立されるまでループで呼び出されます。

特定のセキュリティ サポート プロバイダー (SSP) におけるこの関数の使用については、次のトピックを参照してください。

構文

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

パラメーター

phCredential[in, optional]

AcquireCredentialsHandle (General) によって返される資格情報へのハンドル。 このハンドルは、セキュリティ コンテキストを構築するために使用されます。 InitializeSecurityContext (General) 関数には、少なくとも OUTBOUND 資格情報が必要です。

phContext[in, optional]

CtxtHandle 構造体へのポインター。 InitializeSecurityContext (General) に対する最初の呼び出しでは、このポインターは NULL です。 2 番目の呼び出しでは、このパラメーターは、最初の呼び出しによって phNewContext パラメーターで返される部分的に書式設定されたコンテキストに対するハンドルへのポインターです。

このパラメーターは、Microsoft Digest SSP では省略可能で、NULL に設定できます。

Schannel SSP を使用する場合、InitializeSecurityContext (General) への最初の呼び出しで、NULL に指定します。 今後の呼び出しでは、この関数の最初の呼び出しの後に phNewContext パラメーターで受け取ったトークンを指定します。

pTargetName[in, optional]

コンテキストのターゲットを示す、null 終端文字列へのポインター。 次の表に記載するように、文字列の内容はセキュリティ パッケージ固有です。 このリストは全てを網羅しているわけではありません。 システム SSP とサード パーティ SSP をシステムに追加できます。

fContextReq[in]

コンテキストの要求を示すビット フラグ。 すべてのパッケージですべての要件をサポートできるわけではありません。 このパラメーターに使用されるフラグには、ISC_REQ_DELEGATE など、ISC_REQ_ で始まります。 このパラメーターには、次の 1 つ以上の属性フラグを指定できます。

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

さまざまな属性の詳細な説明については、「コンテキスト要件」を参照してください。

Reserved1[in]

このパラメーターは予約されており、0 に設定する必要があります。

TargetDataRep[in]

ターゲット上のバイト順序などのデータ表現。 このパラメーターには、SECURITY_NATIVE_DREP または SECURITY_NETWORK_DREP を指定できます。

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

pInput[in, optional]

パッケージへの入力として指定されるバッファーへのポインターを含む SecBufferDesc 構造体へのポインター。 クライアント コンテキストがサーバーによって開始された場合を除き、このパラメーターの値は関数に対する最初の呼び出しの NULL にする必要があります。 後続の関数に対する呼び出し時、またはクライアント コンテキストがサーバーで開始されたとき、このパラメーターの値は、リモート コンピューターから返されるトークンを保持するのに十分なメモリが割り当てられたバッファーへのポインターです。

Reserved2[in]

このパラメーターは予約されており、0 に設定する必要があります。

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

出力データを受け取る SecBuffer 構造体へのポインターを含む SecBufferDesc 構造体へのポインター。 バッファーが入力で SEC_READWRITE と入力された場合、出力にもそのバッファーが存在します。 システムは、(ISC_REQ_ALLOCATE_MEMORY 経由で) 要求された場合、セキュリティ トークンにバッファーを割り当て、セキュリティ トークンのバッファー記述子のアドレスを入力します。

Microsoft Digest SSP を使用する場合、このパラメーターは、サーバーに送信する必要があるチャレンジ応答を受け取ります。

Schannel SSP を使用する際に ISC_REQ_ALLOCATE_MEMORY フラグが指定されている場合、Schannel SSP はバッファーのメモリを割り当て、SecBufferDesc に適切な情報を配置します。 さらに、呼び出し元は、SECBUFFER_ALERT 型のバッファーを渡す必要があります。 出力時にアラートが生成されると、このバッファーにそのアラートに関する情報が含まれ、関数は失敗します。

pfContextAttr[out]

確立されたコンテキストの属性を示すビット フラグのセットを受け取る変数へのポインター。 さまざまな属性の説明については、「コンテキスト要件」を参照してください。

このパラメーターに使用されるフラグは、ISC_RET_DELEGATE など、ISC_RET で始まります。 有効な値の一覧については、fContextReq パラメーターを参照してください。

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

ptsExpiry[out, optional]

コンテキストの有効期限を受け取る TimeStamp 構造体へのポインター。 セキュリティ パッケージが常に現地時間でこの値を返すようにすることをお勧めします。 このパラメーターは省略可能であり、NULL は短期間のクライアントに渡す必要があります。

Microsoft Digest SSP セキュリティ コンテキストまたは資格情報に有効期限はありません。

戻り値

関数が成功した場合、関数は次のいずれかの成功コードを返します。

関数が失敗した場合、関数は次のいずれかのエラー コードを返します。

解説

呼び出し元は、最終的なコンテキスト属性が十分かどうかを判断します。 たとえば、機密性が要求されたものの確立できなかった場合、一部のアプリケーションは接続を直ちにシャットダウンすることを選択できます。

セキュリティ コンテキストの属性が十分でない場合、クライアントは DeleteSecurityContext 関数を呼び出して、部分的に作成されたコンテキストを解放する必要があります。

InitializeSecurityContext (General) 関数は、クライアントが送信コンテキストを初期化するために使用します。

2 段階の セキュリティ コンテキストの場合、呼び出しシーケンスは次のようになります。

1. クライアントは、phContext が NULL に設定された関数を呼び出し、バッファー記述子に入力メッセージを入力します。
2. セキュリティ パッケージはパラメーターを調べて不透明なトークンを構築し、バッファー配列の TOKEN 要素に配置します。 fContextReq パラメーターに ISC_REQ_ALLOCATE_MEMORY フラグが含まれている場合、セキュリティ パッケージはメモリを割り当て、TOKEN 要素内のポインターを返します。
3. クライアントは、pOutput バッファーで返されたトークンをターゲット サーバーに送信します。 その後、サーバーは、AcceptSecurityContext (General) 関数の呼び出しで入力引数としてトークンを渡します。
4. AcceptSecurityContext (General) はトークンを返します。このトークンは、最初の呼び出しが SEC_I_CONTINUE_NEEDED を返した場合に、InitializeSecurityContext (General) への 2 回目の呼び出しのためにサーバーがクライアントに送信します。

相互認証など、複数段階のセキュリティ コンテキストの場合、呼び出しシーケンスは次のようになります。

1. クライアントは前述のように関数を呼び出しますが、パッケージは SEC_I_CONTINUE_NEEDED 成功コードを返します。
2. クライアントはサーバーに出力トークンを送信し、サーバーの応答を待機します。
3. サーバーの応答を受信すると、クライアントは InitializeSecurityContext (General) を再度呼び出し、phContext は前回の呼び出しから返されたハンドルに設定されます。 サーバーから受信したトークンは、pInput パラメーターで指定されます。
4. InitializeSecurityContext (General) に対する同時呼び出しでは、phContext を使用しないでください。 セキュリティ プロバイダーの実装はスレッド セーフではありません。

サーバーが正常に応答した場合、セキュリティ パッケージは SEC_E_OK を返し、セキュリティで保護されたセッションが確立されます。

関数がいずれかのエラー応答を返した場合、サーバーの応答は受け入れられず、セッションは確立されません。

関数が SEC_I_CONTINUE_NEEDED、SEC_I_COMPLETE_NEEDED、または SEC_I_COMPLETE_AND_CONTINUE を返す場合は、手順 2 と 3 が繰り返されます。

セキュリティ コンテキストを初期化するには、基になる認証メカニズムと fContextReq パラメーターで指定された選択肢に応じて、この関数の複数の呼び出しが必要になる場合があります。

fContextReq パラメーターと pfContextAttributes パラメーターは、さまざまなコンテキスト属性を表すビットマスクです。 さまざまな属性の説明については、「コンテキスト要件」を参照してください。 pfContextAttributes パラメーターは成功した戻り値で有効ですが、コンテキストのセキュリティの側面に関連するフラグを調べる必要があるのは、最終的な正常の戻り値の場合のみです。 中間の戻り値は、たとえば、ISC_RET_ALLOCATED_MEMORY フラグを設定できます。

ISC_REQ_USE_SUPPLIED_CREDS フラグが設定されている場合、セキュリティ パッケージは pInput 入力バッファーで SECBUFFER_PKG_PARAMS バッファーの種類を検索する必要があります。 これは汎用ソリューションではありませんが、状況に応じてセキュリティ パッケージとアプリケーションの強力なペアリングが可能になります。

ISC_REQ_ALLOCATE_MEMORY が指定された場合、呼び出し元は FreeContextBuffer 関数を呼び出してメモリを解放する必要があります。

たとえば、入力トークンは LAN マネージャーからのチャレンジである可能性があります。 この場合、出力トークンはチャレンジに対する NTLM で暗号化された応答になります。

クライアントが実行するアクションは、この関数からのリターン コードによって異なります。 リターン コードが SEC_E_OK である場合、2 回目の InitializeSecurityContext (General) 呼び出しは行われず、サーバーからの応答は期待されません。 リターン コードが SEC_I_CONTINUE_NEEDED の場合、クライアントはサーバーからの応答でトークンを受け取り、InitializeSecurityContext (General) への 2 回目の呼び出しでそれを渡します。 SEC_I_COMPLETE_NEEDED リターン コードは、クライアントがメッセージの作成を完了し、CompleteAuthToken 関数を呼び出す必要があることを示します。 SEC_I_COMPLETE_AND_CONTINUE コードには、これらの両方のアクションが組み込まれています。

InitializeSecurityContext (General) が最初の (または唯一の) 呼び出しで成功を返す場合、呼び出しが認証交換の後の段階で失敗した場合でも、呼び出し元は最終的に返されたハンドルで DeleteSecurityContext 関数を呼び出す必要があります。

クライアントは、正常に完了した後にl InitializeSecurityContext (General) を再度呼び出す場合があります。 これは、再認証が必要であることをセキュリティ パッケージに示します。

カーネル モードの呼び出し元には、次のような相違があります: ターゲット名は、VirtualAlloc を使用して仮想メモリに割り当てる必要がある Unicode 文字列です。プールから割り当ててはいけません。 pInput および pOutput で渡され、指定されるバッファーは、プール内ではなく仮想メモリ内に存在する必要があります。

Schannel SSP を使用する場合、関数が SEC_I_INCOMPLETE_CREDENTIALS を返す場合は、資格情報に有効で信頼できる証明書を指定したことをチェックします。 証明書は、AcquireCredentialsHandle (General) 関数を呼び出す場合に指定されます。 証明書は、サーバーによって信頼されている証明機関 (CA) によって発行されたクライアント認証証明書である必要があります。 サーバーによって信頼されている CA の一覧を取得するには、QueryContextAttributes (General) 関数を呼び出し、SECPKG_ATTR_ISSUER_LIST_EX 属性を指定します。

Schannel SSP を使用する場合、クライアント アプリケーションがサーバーによって信頼されている CA から認証証明書を受け取った後、アプリケーションは AcquireCredentialsHandle (General) 関数を呼び出し、InitializeSecurityContext (General) をもう一度呼び出して、phCredential パラメーターに新しい資格情報を指定することで、新しい資格情報を作成します。

必要条件

関連項目

SSPI 関数

サービスでの認証のための拡張保護 (EPA) のサポート

AcceptSecurityContext (General)

AcquireCredentialsHandle (General)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc