InitializeSecurityContext (CredSSP) 関数

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

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 資格情報が必要です。

phContext[in, optional]

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

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

警告

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

pTargetName[in, optional]

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

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

fContextReq[in]

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

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

値	意味
ISC_REQ_ALLOCATE_MEMORY `0x100`	セキュリティパッケージは、呼び出し元に出力バッファーを割り当てます。出力バッファーの使用が完了したら、 FreeContextBuffer 関数を呼び出して解放します。
ISC_REQ_CONNECTION `0x800`	セキュリティコンテキストでは、書式設定メッセージは処理されません。
ISC_REQ_EXTENDED_ERROR `0x4000`	エラーが発生すると、リモートパーティに通知されます。
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	資格情報セキュリティサポートプロバイダー (CredSSP) は、サーバーを自動的に認証することはできません。このフラグは、CredSSP を使用するときに常に設定されます。
ISC_REQ_SEQUENCE_DETECT `0x8`	受信したメッセージを順番に検出します。
ISC_REQ_STREAM `0x8000`	ストリーム指向の接続をサポートします。
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP は、クライアントの資格情報を自動的に指定しようとしないでください。
ISC_REQ_DELEGATE `0x1`	ユーザーの資格情報をサーバーに委任することを示します。このフラグを指定しない場合、空の資格情報のセットがサーバーに委任されます。 Windows Server 2008 と Windows Vista: このフラグは必須です。
ISC_REQ_MUTUAL_AUTH `0x2`	サーバー認証が必要ないことを示します。このフラグが指定されていない場合でも、委任ポリシーは適用されます。 Windows Server 2008 と Windows Vista: このフラグは無視されます。

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

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

予約済み 1[in]

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

TargetDataRep[in]

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

pInput[in, out, optional]

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

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

予約済み 2[in]

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

phNewContext[in, out, optional]

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

pOutput[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 フラグなど) は、最終的な戻り値の前に確認できます。

注意

特定のコンテキスト属性は、リモートピアとのネゴシエーション中に変更される可能性があります。

ptsExpiry[out, optional]

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

戻り値

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

リターンコード	説明
SEC_E_INCOMPLETE_MESSAGE	メッセージ全体のデータがネットワークから読み取られなかった。この値が返されると、pInput バッファーには、SECBUFFER_MISSING の BufferType メンバーを持つ SecBuffer 構造体が含まれます。 SecBuffer の cbBuffer メンバーは、この関数が成功する前に、関数がクライアントから読み取る必要がある追加のバイト数を指定します。この数値は常に正確であるとは限りませんが、を使用すると、この関数の複数の呼び出しを回避することでパフォーマンスを向上させることができます。
SEC_E_OK	セキュリティコンテキストが正常に初期化されました。別の InitializeSecurityContext (CredSSP) 呼び出しは必要ありません。関数が出力トークンを返す場合 (つまり、pOutput のSECBUFFER_TOKENが 0 以外の長さである場合)、そのトークンをサーバーに送信する必要があります。
SEC_I_COMPLETE_AND_CONTINUE	クライアントは CompleteAuthToken を呼び出し、出力をサーバーに渡す必要があります。その後、クライアントは返されたトークンを待機し、別の呼び出しで InitializeSecurityContext (CredSSP) に渡します。
SEC_I_COMPLETE_NEEDED	クライアントはメッセージの作成を完了し、 CompleteAuthToken 関数を呼び出す必要があります。
SEC_I_CONTINUE_NEEDED	クライアントは出力トークンをサーバーに送信し、戻りトークンを待機する必要があります。クライアントは、 InitializeSecurityContext (CredSSP) の別の呼び出しで返されたトークンを渡します。出力トークンは空にすることができます。
SEC_I_INCOMPLETE_CREDENTIALS	サーバーはクライアント認証を要求しましたが、指定された資格情報に証明書が含まれていないか、サーバーが信頼する証明機関によって証明書が発行されませんでした。詳細については、「解説」を参照してください。

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

リターンコード	説明
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 パラメーターの値が無効です。必須フラグが指定されていないか、CredSSP でサポートされていないフラグが指定されました。
SEC_E_WRONG_PRINCIPAL	認証要求を受け取ったプリンシパルは、 pszTargetName パラメーターに渡されたものと同じではありません。このエラーは、相互認証の失敗を示します。
SEC_E_DELEGATION_POLICY	ポリシーでは、ターゲットサーバーへの資格情報の委任はサポートされていません。
SEC_E_POLICY_NLTM_ONLY	相互認証が達成されない場合、ターゲットサーバーへの資格情報の委任は許可されません。
SEC_E_MUTUAL_AUTH_FAILED	fContextReq パラメーターに ISC_REQ_MUTUAL_AUTH フラグが指定されている場合、サーバー認証に失敗しました。

解説

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

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

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

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

クライアントは 、phContext をに設定して関数を NULL 呼び出し、バッファー記述子に入力メッセージを入力します。
セキュリティパッケージは、パラメーターを調べて不透明なトークンを構築し、バッファー配列の TOKEN 要素に配置します。 fContextReq パラメーターに ISC_REQ_ALLOCATE_MEMORY フラグが含まれている場合、セキュリティパッケージはメモリを割り当て、TOKEN 要素内のポインターを返します。
クライアントは 、pOutput バッファーで返されたトークンをターゲットサーバーに送信します。その後、サーバーは AcceptSecurityContext (CredSSP) 関数の呼び出しでトークンを入力引数として渡します。
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 パラメーターに新しい資格情報を指定します。

要件

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