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
정보를 검색할 액세스 토큰에 대한 핸들입니다.
[in] TokenInformationClass
검색할 정보의 형식을 식별하는 TOKEN_INFORMATION_CLASS 열거형 형식의 값입니다. 이 매개 변수의 가능한 값은 TokenInformation 매개 변수에 대한 설명에 표시된 테이블의 TokenInformationClass 값 열에 나열됩니다.
[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을 받습니다.
반환 값
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 사례 시나리오에서 함수는 액세스 위반 예외를 발생합니다.
보안 및 액세스 제어에 대한 자세한 내용은 드라이버 개발자를 위한
메모
NtQueryInformationToken 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwQueryInformationToken" 대신 이름 "NtQueryInformationToken ""을 사용해야 합니다.
커널 모드 드라이버의 호출의 경우 NtXxx 및 ZwXxx 버전의 Windows Native System Services 루틴은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP |
| 대상 플랫폼 | 보편적 |
| 헤더 | ntifs.h(Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL |
PASSIVE_LEVEL |
| DDI 규정 준수 규칙 |
HwStorPortProhibitedDDIs, PowerIrpDDis |
참고 항목
ACL
SeQueryInformationToken
ZwSetInformationToken