InitializeSecurityContextW 関数 (sspi.h)

  • [アーティクル]

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

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

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

トピック 説明
InitializeSecurityContext (CredSSP) 資格情報セキュリティ サポート プロバイダー (CredSSP) を使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Digest) Digest セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (Kerberos) Kerberos セキュリティ パッケージを使用して、資格情報ハンドルからクライアント側の送信セキュリティ コンテキストを開始します。
InitializeSecurityContext (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とサードパーティSSPをシステムに追加できます。

使用中の 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 フラグは無視されます。

この値は、ネゴシエートおよび 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 パラメーターとして渡し、phNewContext に NULL を指定します。

[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 バッファーには、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 パラメーターで指定されます。
サーバーが正常に応答した場合、セキュリティ パッケージは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 関数を呼び出す必要があります。

クライアントは、正常に完了した後に 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 ヘッダーは InitializeSecurityContext をエイリアスとして定義します。これは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー sspi.h (Security.h を含む)
Library Secur32.lib
[DLL] Secur32.dll

こちらもご覧ください

AcceptSecurityContext (全般)

AcquireCredentialsHandle (全般)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SSPI 関数

SecBuffer

SecBufferDesc