次の方法で共有

InitializeSecurityContextW 関数 (sspi.h)

  • [アーティクル]

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 セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。

構文

KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY InitializeSecurityContextW(
  [in, optional]      PCredHandle      phCredential,
  [in, optional]      PCtxtHandle      phContext,
  [in, optional]      PSECURITY_STRING pTargetName,
  [in]                unsigned long    fContextReq,
  [in]                unsigned long    Reserved1,
  [in]                unsigned long    TargetDataRep,
  [in, optional]      PSecBufferDesc   pInput,
  [in]                unsigned long    Reserved2,
  [in, out, optional] PCtxtHandle      phNewContext,
  [in, out, optional] PSecBufferDesc   pOutput,
  [out]               unsigned long    *pfContextAttr,
  [out, optional]     PTimeStamp       ptsExpiry
);

パラメーター

[in, optional] phCredential

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

[in, optional] phContext

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

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

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

[in, optional] pTargetName

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

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

[in] fContextReq

コンテキストの要求を示すビット フラグ。 すべてのパッケージですべての要件をサポートできるわけではありません。 このパラメーターに使用されるフラグには、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 のダイジェストを使用します。 SASL メカニズムとしてダイジェストを使用するには、このフラグを省略します。
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 パラメーターを参照してください。

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

[in] Reserved1

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

[in] TargetDataRep

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

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

[in, optional] pInput

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

[in] Reserved2

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

[in, out, optional] phNewContext

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

Schannel SSP を使用する場合、最初の呼び出しの後の呼び出しで、ここで返されたハンドルを phContext パラメーターとして渡し、phNewContextnull 指定します。

[in, out, optional] pOutput

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

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

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

[out] pfContextAttr

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

このパラメーターに使用されるフラグには、ISC_RET_DELEGATEなどのISC_RETが付きます。

有効な値の一覧については、fContextReq パラメーター を参照してください。

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

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

[out, optional] ptsExpiry

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

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

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

手記

sspi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして InitializeSecurityContext を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー sspi.h (Security.h を含む)
ライブラリ Secur32.lib
DLL Secur32.dll

関連項目

AcceptSecurityContext (全般) の

AcquireCredentialsHandle (General)

CompleteAuthToken の

DeleteSecurityContext の

FreeContextBuffer の

SSPI 関数の

SecBuffer

SecBufferDesc