InitializeSecurityContext (CredSSP) 関数

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

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

構文

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

パラメーター

phCredential (英語)[in, optional]

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

phコンテキスト[in, optional]

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

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

pTargetName の[in, optional]

ターゲット サーバーを一意に識別する null で終わる文字列へのポインター。 Schannel は、この値を使用してサーバー証明書を確認します。 Schannel は、接続を再確立するときに、この値を使用してセッション キャッシュ内のセッションを検索します。 キャッシュされたセッションは、次のすべての条件が満たされている場合にのみ使用されます。

• ターゲット名は同じです。
• キャッシュ エントリの有効期限が切れていない。
• 関数を呼び出すアプリケーション プロセスは同じです。
• ログオン セッションは同じです。
• 資格情報ハンドルは同じです。

fContextReq[in]

コンテキストの要求を示すビット フラグ。 すべてのパッケージですべての要件をサポートできるわけではありません。 このパラメーターに使用されるフラグには、ISC_REQ_DELEGATEなど、ISC_REQ_がプレフィックスとして付けられます。

このパラメーターには、次の属性フラグの 1 つ以上を指定できます。

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

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

予約済み 1[in]

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

ターゲットデータ担当者[in]

ターゲット上のバイト順序などのデータ表現。 このパラメータは、 SECURITY_NATIVE_DREP または SECURITY_NETWORK_DREP のいずれかになります。

p入力[in, out, optional]

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

最初の呼び出し後にこの関数を呼び出す場合は、2 つのバッファーが必要です。 1 つ目 の型SECBUFFER_TOKEN があり、サーバーから受信したトークンが含まれています。 2 番目のバッファーの型は SECBUFFER_EMPTY; です。 pvBuffer メンバーと cbBuffer メンバーの両方をゼロに設定します。

予約済み 2[in]

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

phNewContext[in, out, optional]

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

p出力[out, optional]

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

ISC_REQ_ALLOCATE_MEMORY フラグが指定されている場合、CredSSP はバッファーのメモリを割り当て、適切な情報を SecBufferDesc に格納します。

pfContextAttr[out]

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

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

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

pts有効期限[out, optional]

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

戻り値

関数が成功すると、次のいずれかの成功コードが返されます。

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

注釈

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

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

クライアントは InitializeSecurityContext (CredSSP) 関数を呼び出して、送信コンテキストを初期化します。

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

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

サーバーが正常に応答した場合、セキュリティ パッケージは 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 (CredSSP) 呼び出しはなく、サーバーからの応答は期待されません。 戻りコードが SEC_I_CONTINUE_NEEDED場合、クライアントはサーバーからの応答でトークンを受け取り、 InitializeSecurityContext (CredSSP) への 2 回目の呼び出しでそれを渡します。 SEC_I_COMPLETE_NEEDEDリターン コードは、クライアントがメッセージの作成を完了し、CompleteAuthToken 関数を呼び出す必要があることを示します。 SEC_I_COMPLETE_AND_CONTINUE コードには、これらの両方のアクションが組み込まれています。

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

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

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

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

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

必要条件

こちらもご覧ください

SSPI 関数

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

コンプリートAuthToken

削除セキュリティコンテキスト

フリーコンテキストバッファ

SecBuffer (英語)

SecBufferDesc