InitializeSecurityContextA 関数 (sspi.h)

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

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

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

構文

SECURITY_STATUS SEC_ENTRY InitializeSecurityContextA(
  [in, optional]      PCredHandle    phCredential,
  [in, optional]      PCtxtHandle    phContext,
                      SEC_CHAR       *pszTargetName,
  [in]                unsigned long  fContextReq,
  [in]                unsigned long  Reserved1,
  [in]                unsigned long  TargetDataRep,
  [in, optional]      PSecBufferDesc pInput,
  [in]                unsigned long  Reserved2,
  [in, out, optional] PCtxtHandle    phNewContext,
  [in, out, optional] PSecBufferDesc pOutput,
  [out]               unsigned long  *pfContextAttr,
  [out, optional]     PTimeStamp     ptsExpiry
);

パラメーター

[in, optional] phCredential

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

[in, optional] phContext

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

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

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

pszTargetName

TBD

[in] fContextReq

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

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

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

[in] Reserved1

このパラメーターは予約済みであり、0 に設定する必要があります。

[in] TargetDataRep

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

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

[in, optional] pInput

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

[in] Reserved2

このパラメーターは予約済みであり、0 に設定する必要があります。

[in, out, optional] phNewContext

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

Schannel SSP を使用する場合、最初の呼び出し後の呼び出しで、ここで返されたハンドルを phContext パラメーターとして渡し、phNewContext に NULL を指定します。

[in, out, optional] pOutput

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

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

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

[out] pfContextAttr

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

このパラメーターに使用されるフラグには、ISC_RET_DELEGATEなどのISC_RETがプレフィックスとして付けられます。

有効な値の一覧については、 fContextReq パラメーターを参照してください。

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

[out, optional] ptsExpiry

コンテキストの有効期限を受け取る 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 パラメーターで指定されます。

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

関数が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 関数を呼び出す必要があります。

クライアントは、正常に完了した後に 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 パラメーターに新しい資格情報を指定して新しい資格情報を作成します。

要件

こちらもご覧ください

AcceptSecurityContext (全般)

AcquireCredentialsHandle (全般)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SSPI 関数

SecBuffer

SecBufferDesc