次の方法で共有

InitializeSecurityContext (General) 関数

  • [アーティクル]

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

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

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

トピック 説明
InitializeSecurityContext (CredSSP) 資格情報セキュリティ サポート プロバイダー (CredSSP) セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Digest) Digest セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Kerberos) Kerberos セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Negotiate) Negotiate セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (NTLM) NTLM セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Schannel) Schannel セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。

構文

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

phContext[in, optional]

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

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

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

警告

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

pTargetName[in, optional]

コンテキストのターゲットを示す、null 終端文字列へのポインター。 次の表に記載するように、文字列の内容はセキュリティ パッケージ固有です。 このリストは全てを網羅しているわけではありません。 システム SSP とサード パーティ SSP をシステムに追加できます。

使用中の SSP 意味
Digest 要求されたリソースの URI を一意に識別する、null 終端文字列。 文字列は、URI で許可される文字で構成され、US ASCII コード セットで表現できるようにする必要があります。 パーセント エンコードは、US ASCII コード セットの外部にある文字を表すために使用できます。
Kerberos または Negotiate サービス プリンシパル名 (SPN) または移行先サーバーのセキュリティ コンテキスト。
NTLM サービス プリンシパル名 (SPN) または移行先サーバーのセキュリティ コンテキスト。
Schannel/SSL ターゲット サーバーを一意に識別する、null 終端文字列。 Schannel は、サーバー証明書を確認するためにこの値を使用します。 また、Schannel は、接続を再確立する場合に、セッション キャッシュ内のセッションを検索するためにこの値を使用します。 キャッシュされたセッションは、次のすべての条件を満たす場合にのみ使用されます。
-ターゲット名は同じです。
-キャッシュ エントリの有効期限が切れていない。
-関数を呼び出すアプリケーション プロセスは同じです。
-ログオン セッションは同じです。
-資格情報ハンドルは同じです。

fContextReq[in]

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

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

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

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

Reserved1[in]

このパラメーターは予約されており、0 に設定する必要があります。

TargetDataRep[in]

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

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

pInput[in, optional]

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

Reserved2[in]

このパラメーターは予約されており、0 に設定する必要があります。

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

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

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

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

pfContextAttr[out]

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

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

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

Note

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

ptsExpiry[out, optional]

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

Microsoft Digest SSP セキュリティ コンテキストまたは資格情報に有効期限はありません。

戻り値

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

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

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

リターン コード 説明
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 (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 パラメーターで指定されます。
  4. InitializeSecurityContext (General) に対する同時呼び出しでは、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 (General) 呼び出しは行われず、サーバーからの応答は期待されません。 リターン コードが SEC_I_CONTINUE_NEEDED の場合、クライアントはサーバーからの応答でトークンを受け取り、InitializeSecurityContext (General) への 2 回目の呼び出しでそれを渡します。 SEC_I_COMPLETE_NEEDED リターン コードは、クライアントがメッセージの作成を完了し、CompleteAuthToken 関数を呼び出す必要があることを示します。 SEC_I_COMPLETE_AND_CONTINUE コードには、これらの両方のアクションが組み込まれています。

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

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

必要条件

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

関連項目

SSPI 関数

サービスでの認証のための拡張保護 (EPA) のサポート

AcceptSecurityContext (General)

AcquireCredentialsHandle (General)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc