NtQueryInformationToken 関数 (ntifs.h)
NtQueryInformationToken ルーチンは、アクセス トークンに関する指定された種類の情報を取得します。 呼び出し元プロセスには、情報を取得するための適切なアクセス権が必要です。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
[in] HANDLE TokenHandle,
[in] TOKEN_INFORMATION_CLASS TokenInformationClass,
[out] PVOID TokenInformation,
[in] ULONG TokenInformationLength,
[out] PULONG ReturnLength
);
パラメーター
[in] TokenHandle
情報の取得元となるアクセス トークンのハンドル。 TokenInformationClass が TokenSource に設定されている場合、ハンドルにはTOKEN_QUERY_SOURCEアクセス権が必要です。 他のすべての TokenInformationClass 値については、ハンドルにTOKEN_QUERYアクセス権が必要です。 アクセス トークン オブジェクトのアクセス権の詳細については、Windows SDK ドキュメントのセキュリティに関するセクションを参照してください。
[in] TokenInformationClass
取得 する情報 の種類を識別する列挙型TOKEN_INFORMATION_CLASSからの値。 このパラメーターに指定できる値は、 TokenInformation パラメーターの説明に示されているテーブルの TokenInformationClass Value 列に一覧表示されます。
[out] TokenInformation
トークンに関する要求された情報を受信する呼び出し元によって割り当てられたバッファーへのポインター。 このバッファーに格納される構造体は、次の表に示すように、 TokenInformationClass の値によって異なります。 すべての構造体は、32 ビット境界に配置する必要があります。
| TokenInformationClass 値 | TokenInformation バッファーへの影響 |
|---|---|
| TokenDefaultDacl | バッファーは、新しく作成されたオブジェクトの既定の DACL を含むTOKEN_DEFAULT_DACL構造体を受け取ります。 |
| TokenGroups | バッファーは、トークンに関連付けられているグループ アカウントを含む TOKEN_GROUPS 構造体を受け取ります。 |
| TokenImpersonationLevel | バッファーは、トークンの偽装レベルを示す SECURITY_IMPERSONATION_LEVEL 値を受け取ります。 アクセス トークンが偽装トークンでない場合、 NtQueryInformationToken の呼び出しは失敗します。 |
| TokenOwner | バッファーは、新しく作成されたオブジェクトの既定の所有者 SID を含むTOKEN_OWNER構造体を受け取ります。 |
| TokenPrimaryGroup | バッファーは、新しく作成されたオブジェクトの既定のプライマリ グループ SID を含む TOKEN_PRIMARY_GROUP 構造体を受け取ります。 |
| TokenPrivileges | バッファーは、トークンの特権を含む TOKEN_PRIVILEGES 構造体を受け取ります。 |
| TokenSessionId | バッファーは、トークンに関連付けられているターミナル サービス セッション識別子を指定する 32 ビットの値を受け取ります。 トークンがターミナル サーバー コンソール セッションに関連付けられている場合、セッション識別子は 0 です。 0 以外のセッション識別子は、ターミナル サービス クライアント セッションを示します。 ターミナル サービス以外の環境では、セッション識別子は 0 です。 |
| TokenSource | バッファーは、トークンのソースを含む TOKEN_SOURCE 構造体を受け取ります。 この情報TOKEN_QUERY_SOURCE取得するには、アクセス権が必要です。 |
| TokenStatistics | バッファーは、さまざまなトークン統計を含む TOKEN_STATISTICS 構造体を受け取ります。 |
| Tokentype | バッファーは、トークンがプライマリ トークンか偽装トークンかを示す TOKEN_TYPE 値を受け取ります。 |
| TokenUser | バッファーは、トークンのユーザー アカウントを含む TOKEN_USER 構造体を受け取ります。 |
[in] TokenInformationLength
呼び出し元によって割り当てられた TokenInformation バッファーの長さ (バイト単位)。
[out] ReturnLength
TokenInformation バッファーで返される情報の実際の長さをバイト単位で受け取る呼び出し元割り当て変数へのポインター。 次のいずれかの条件が true の場合、 TokenInformation バッファーにデータは返されません。
要求されたトークン情報構造体のサイズが TokenInformationLength を超えています。 この場合、 ReturnLength は、要求された情報を格納するために必要な実際のバイト数を受け取ります。
TokenInformationClass の値は TokenDefaultDacl であり、トークンの既定の DACL は確立されていません。 この場合、 ReturnLength は 0 を受け取ります。
ReturnLength を NULL にすることはできません。 詳細については、「解説」を参照してください。
戻り値
NtQueryInformationToken は、STATUS_SUCCESSまたは適切なエラー状態を返します。 考えられるエラー状態コードは次のとおりです。
| リターン コード | 説明 |
|---|---|
| STATUS_ACCESS_DENIED | TokenHandle に必要なアクセス権がありませんでした。 |
| STATUS_BUFFER_TOO_SMALL | 要求されたトークン情報構造体のサイズが TokenInformationLength を超えています。 必要なバイト数は ReturnLength で返されます。 |
| STATUS_ACCESS_VIOLATION | ReturnLength が NULL であるか、 TokenInformation が指す情報の実際の長さを受け取るために書き込み可能ではなかった。 |
| STATUS_INVALID_HANDLE | TokenHandle が有効なハンドルではありません。 |
| STATUS_INVALID_INFO_CLASS | TokenInformationClass は有効なトークン情報クラスではありません。 |
| STATUS_OBJECT_TYPE_MISMATCH | TokenHandle はトークン ハンドルではありません。 |
注釈
NtQueryInformationToken ルーチンは、ファイル システムまたはファイル システム フィルター ドライバーによって、IRP_MJ_CREATE処理中に要求を開始した呼び出し元の SID を決定するために使用できます。 NtQueryInformationToken に渡される TokenInformationClass パラメーターに TokenUser が指定されている場合は、TokenInformation パラメーターが指すバッファーにTOKEN_USER構造体が返されます。 この返されるバッファーには、ユーザー SID を持つSID_AND_ATTRIBUTES構造体が含まれています。
トークンのプロパティ (トークン ユーザー、トークン プライマリ グループ、特権など、各トークンで内容が異なる) の性質上、 ReturnLength は省略可能ではありません。つまり、NULL にすることはできません。 これは、SID は可変長構造体であるのに対し、特定の特権はトークン内に存在する可能性がありますが、別のトークンには存在しないためです (特権の数はトークンごとに異なる場合があります)。 実際のクエリを実行する前に、要求されたトークン情報に対応するためにメモリを割り当てるために、最初に必要な長さのサイズを照会するのは呼び出し元の責任です。 つまり、NULL ではなく書き込み可能な有効な ReturnLength 変数を指定することも呼び出し元の責任です。 NULL の場合、関数はアクセス違反の例外を発生させます。
セキュリティとアクセス制御の詳細については、 ドライバー開発者向けの Windows セキュリティ モデル と、Windows SDK のこれらのトピックに関するドキュメントを参照してください。
注意
NtQueryInformationToken 関数の呼び出しがユーザー モードで発生する場合は、"ZwQueryInformationToken" ではなく "NtQueryInformationToken" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx バージョンと ZwXxx バージョンの間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDIs、PowerIrpDDis |