InitializeSecurityContext (Kerberos) 関数

[アーティクル]
03/18/2023

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

警告

InitializeSecurityContext (Kerberos) の同時呼び出しでは、同じコンテキストハンドルを使用しないでください。セキュリティサービスプロバイダーの API 実装はスレッドセーフではありません。

pszTargetName[in]

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

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

fContextReq[in]

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

値	意味
ISC_REQ_ALLOCATE_MEMORY	セキュリティパッケージは、出力バッファーを割り当てます。出力バッファーの使用が完了したら、 FreeContextBuffer 関数を呼び出して解放します。
ISC_REQ_CONFIDENTIALITY	EncryptMessage 関数を使用してメッセージを暗号化します。
ISC_REQ_CONNECTION	セキュリティコンテキストでは、書式設定メッセージは処理されません。この値は既定値です。
ISC_REQ_DELEGATE	サーバーは、コンテキストを使用して、クライアントとして他のサーバーに対して認証を行うことができます。このフラグを機能させるには、ISC_REQ_MUTUAL_AUTH フラグを設定する必要があります。 Kerberos に対して有効です。制約付き委任の場合は、このフラグを無視します。
ISC_REQ_EXTENDED_ERROR	エラーが発生すると、リモートパーティに通知されます。
ISC_REQ_INTEGRITY	EncryptMessage 関数と MakeSignature 関数を使用して、メッセージに署名し、署名を確認します。
ISC_REQ_MUTUAL_AUTH	サービスの相互認証ポリシーが満たされます。注意：これは、必ずしも相互認証が実行されるという意味ではなく、サービスの認証ポリシーが満たされていることを意味します。相互認証を確実に実行するには、 QueryContextAttributes (Kerberos) 関数を呼び出します。
ISC_REQ_NO_INTEGRITY	このフラグが設定されている場合、 ISC_REQ_INTEGRITY フラグは無視されます。
ISC_REQ_REPLAY_DETECT	EncryptMessage 関数または MakeSignature 関数を使用してエンコードされた再生済みメッセージを検出します。
ISC_REQ_SEQUENCE_DETECT	受信したメッセージを順番に検出します。
ISC_REQ_STREAM	ストリーム指向の接続をサポートします。
ISC_REQ_USE_SESSION_KEY	新しいセッションキーをネゴシエートする必要があります。

要求された属性は、クライアントでサポートされていない可能性があります。詳細については、 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 有効期間の短いクライアントにはを渡す必要があります。

戻り値

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

リターンコード	説明
SEC_E_OK	セキュリティコンテキストが正常に初期化されました。別の InitializeSecurityContext (Kerberos) 呼び出しは必要ありません。関数が出力トークンを返す場合、つまり pOutput のSECBUFFER_TOKENの長さが 0 以外の場合は、そのトークンをサーバーに送信する必要があります。
SEC_I_COMPLETE_AND_CONTINUE	クライアントは CompleteAuthToken を呼び出し、出力をサーバーに渡す必要があります。その後、クライアントは返されたトークンを待機し、別の呼び出しで InitializeSecurityContext (Kerberos) に渡します。
SEC_I_COMPLETE_NEEDED	クライアントはメッセージの作成を完了し、 CompleteAuthToken 関数を呼び出す必要があります。
SEC_I_CONTINUE_NEEDED	クライアントは出力トークンをサーバーに送信し、戻りトークンを待機する必要があります。返されたトークンは、 InitializeSecurityContext (Kerberos) の別の呼び出しで渡されます。出力トークンは空にすることができます。
SEC_I_INCOMPLETE_CREDENTIALS	Schannel でを使用します。サーバーはクライアント認証を要求しており、指定された資格情報に証明書が含まれていないか、サーバーによって信頼されている証明機関 (CA) によって証明書が発行されていません。詳細については、「解説」をご覧ください。

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

リターンコード	説明
SEC_E_INSUFFICIENT_MEMORY	要求されたアクションを完了するのに十分なメモリがありません。
SEC_E_INTERNAL_ERROR	SSPI エラーコードにマップされないエラーが発生しました。
SEC_E_INVALID_HANDLE	関数に渡されたハンドルが無効です。
SEC_E_INVALID_TOKEN	このエラーは、転送中に破損したトークン、サイズが正しくないトークン、間違った制約付き委任に渡されたトークンなど、入力トークンの形式が正しくないことが原因です。クライアントとサーバーが適切な制約付き委任をネゴシエートしなかった場合、間違ったパッケージにトークンを渡すと発生する可能性があります。
SEC_E_LOGON_DENIED	ログオンに失敗しました。
SEC_E_NO_AUTHENTICATING_AUTHORITY	認証のために機関に連絡できませんでした。認証パーティのドメイン名が間違っているか、ドメインに到達できないか、信頼関係エラーが発生している可能性があります。
SEC_E_NO_CREDENTIALS	制約付き委任では、資格情報を使用できません。
SEC_E_TARGET_UNKNOWN	ターゲットが認識されませんでした。
SEC_E_UNSUPPORTED_FUNCTION	fContextReq パラメーターで無効なコンテキスト属性フラグ (ISC_REQ_DELEGATEまたはISC_REQ_PROMPT_FOR_CREDS) が指定されました。
SEC_E_WRONG_PRINCIPAL	認証要求を受け取ったプリンシパルは、 pszTargetName パラメーターに渡されたものと同じではありません。これは、相互認証の失敗を示します。

解説

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

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

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

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

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

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

クライアントは前述のように関数を呼び出しますが、パッケージはSEC_I_CONTINUE_NEEDED成功コードを返します。
クライアントは出力トークンをサーバーに送信し、サーバーの応答を待機します。
サーバーの応答を受信すると、クライアントは InitializeSecurityContext (Kerberos) を再度呼び出し、 phContext は最後の呼び出しから返されたハンドルに設定されます。サーバーから受信したトークンは pInput パラメーターで指定されます。
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 で渡され、提供されるバッファーは、プール内ではなく仮想メモリ内に存在する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ]
Header	Sspi.h (Security.h を含む)
ライブラリ	Secur32.lib
[DLL]	Secur32.dll