次の方法で共有

InitializeSecurityContext (NTLM) 関数

  • [アーティクル]

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

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

構文

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

phContext[in, optional]

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

警告

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

pszTargetName[in]

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

アプリケーションは、再生攻撃を軽減するために有効な SPN を提供する必要があります。

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

fContextReq[in]

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

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

要求された属性は、クライアントでサポートされていない可能性があります。 詳細については、 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 (NTLM) の最初の呼び出しで、このポインターは新しいコンテキスト ハンドルを受け取ります。 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 (NTLM) 呼び出しは必要ありません。 関数が出力トークンを返す場合、つまり pOutput のSECBUFFER_TOKENの長さが 0 以外の場合は、そのトークンをサーバーに送信する必要があります。
SEC_I_COMPLETE_AND_CONTINUE クライアントは CompleteAuthToken を 呼び出し、出力をサーバーに渡す必要があります。 その後、クライアントは返されたトークンを待機し、別の呼び出しで InitializeSecurityContext (NTLM) に渡します。
SEC_I_COMPLETE_NEEDED クライアントはメッセージの作成を完了し、 CompleteAuthToken 関数を呼び出す必要があります。
SEC_I_CONTINUE_NEEDED クライアントは出力トークンをサーバーに送信し、戻りトークンを待つ必要があります。 返されたトークンは、 InitializeSecurityContext (NTLM) の別の呼び出しで渡されます。 出力トークンは空にすることができます。

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

リターン コード 説明
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 (NTLM) 関数は、クライアントが送信コンテキストを初期化するために使用します。

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

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

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

  1. クライアントは前述のように関数を呼び出しますが、パッケージは成功コードSEC_I_CONTINUE_NEEDED返します。
  2. クライアントは出力トークンをサーバーに送信し、サーバーの応答を待機します。
  3. サーバーの応答を受信すると、クライアントは InitializeSecurityContext (NTLM) を再度呼び出し、 phContext は最後の呼び出しから返されたハンドルに設定されます。 サーバーから受信したトークンは、 pInput パラメーターで指定されます。
  4. InitializeSecurityContext (NTLM) の同時呼び出しでは 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 (NTLM) 呼び出しはなく、サーバーからの応答は期待されません。 戻りコードがSEC_I_CONTINUE_NEEDED場合、クライアントはサーバーからの応答としてトークンを受け取り、 InitializeSecurityContext (NTLM) の 2 回目の呼び出しで渡します。 SEC_I_COMPLETE_NEEDED戻りコードは、クライアントがメッセージの作成を完了し、 CompleteAuthToken 関数を呼び出す必要があることを示します。 SEC_I_COMPLETE_AND_CONTINUE コードには、これらの両方のアクションが組み込まれています。

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

クライアントは、正常に完了した後に InitializeSecurityContext (NTLM) を再度呼び出す場合があります。 これは、再認証が必要であることを セキュリティ パッケージ に示します。

カーネル モードの呼び出し元には、次の違いがあります。ターゲット名は、VirtualAlloc を使用して仮想メモリに割り当てる必要がある Unicode 文字列です。プールから割り当ててはいけません。 pInput と pOutput で渡され、提供されるバッファーは、プール内ではなく仮想メモリ内に存在する必要があります。

要件

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

こちらもご覧ください

SSPI 関数

AcceptSecurityContext (NTLM)

AcquireCredentialsHandle (NTLM)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc