InitializeSecurityContext (Kerberos) 関数

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

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

構文

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_        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 (Kerberos) によって返される資格情報のハンドル。 このハンドルは、 セキュリティ コンテキストを構築するために使用されます。 InitializeSecurityContext (Kerberos) 関数には、少なくとも OUTBOUND 資格情報が必要です。

phContext[in, optional]

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

pszTargetName[in]

サービス プリンシパル名 (SPN) または移行先サーバーの セキュリティ コンテキスト を示す null で終わる文字列へのポインター。

短い名前はフォレスト間でサポートされていないため、完全修飾ターゲット名を使用します。

fContextReq[in]

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

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

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

予約済み 1[in]

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

TargetDataRep[in]

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

pInput[in, optional]

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

予約済み 2[in]

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

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

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

pfContextAttr[out]

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

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

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

ptsExpiry[out, optional]

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

戻り値

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

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

解説

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

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

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

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

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

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

1. クライアントは前述のように 関数を呼び出しますが、パッケージはSEC_I_CONTINUE_NEEDED成功コードを返します。
2. クライアントは出力トークンをサーバーに送信し、サーバーの応答を待機します。
3. サーバーの応答を受信すると、クライアントは InitializeSecurityContext (Kerberos) を再度呼び出し、 phContext は最後の呼び出しから返されたハンドルに設定されます。 サーバーから受信したトークンは pInput パラメーターで指定されます。
4. InitializeSecurityContext (Kerberos) の同時呼び出しでは 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 (Kerberos) 呼び出しはなく、サーバーからの応答は必要ありません。 戻りコードがSEC_I_CONTINUE_NEEDED場合、クライアントはサーバーからの応答でトークンを受け取り、 InitializeSecurityContext (Kerberos) の 2 回目の呼び出しで渡します。 SEC_I_COMPLETE_NEEDED戻りコードは、クライアントがメッセージの作成を完了し、 CompleteAuthToken 関数を呼び出す必要があることを示します。 SEC_I_COMPLETE_AND_CONTINUE コードには、これらのアクションの両方が組み込まれています。

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

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

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

要件

こちらもご覧ください

SSPI 関数

AcceptSecurityContext (Kerberos)

AcquireCredentialsHandle (Kerberos)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc