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

정보를 검색할 액세스 토큰에 대한 핸들입니다. TokenInformationClassTokenSource로 설정된 경우 핸들에 TOKEN_QUERY_SOURCE 액세스 권한이 있어야 합니다. 다른 모든 TokenInformationClass 값의 경우 핸들에 TOKEN_QUERY 액세스 권한이 있어야 합니다. 액세스 토큰 개체에 대한 액세스 권한에 대한 자세한 내용은 Windows SDK 설명서의 보안 섹션을 참조하세요.

[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을 받습니다.

ReturnLengthNULL일 수 없습니다. 자세한 내용은 비고를 참조하세요.

반환 값

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를 확인할 수 있습니다. TokenUserNtQueryInformationToken에 전달된 TokenInformationClass 매개 변수에 대해 지정된 경우 tokenInformation 매개 변수가 가리키는 버퍼에 TOKEN_USER 구조가 반환됩니다. 이 반환된 버퍼에는 사용자 SID가 있는 SID_AND_ATTRIBUTES 구조가 포함됩니다.

토큰 속성의 특성(예: 토큰 사용자, 토큰 기본 그룹, 권한 등) 콘텐츠가 각 토큰에 따라 달라질 수 있기 때문에 ReturnLength 는 선택 사항이 아닙니다. 즉, NULL일 수 없습니다. SID는 가변 길이 구조인 반면 특정 권한은 토큰에 있을 수 있지만 다른 토큰에는 존재할 수 없기 때문입니다(권한 수는 각 토큰마다 다를 수 있음). 실제 쿼리를 수행하기 전에 요청된 토큰 정보를 수용하기 위해 메모리를 할당하기 위해 필요한 길이 크기를 먼저 쿼리하는 것은 호출자의 책임입니다. 즉, 쓰기 가능하고 NULL이 아닌 유효한 ReturnLength 변수를 제공하는 것은 호출자의 책임이기도 합니다. NULL 사례 시나리오에서 함수는 액세스 위반 예외를 발생합니다.

보안 및 액세스 제어에 대한 자세한 내용은 Windows SDK의 이러한 항목에 대한 설명서를 참조하세요.

참고

NtQueryInformationToken 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwQueryInformationToken" 대신 "NtQueryInformationToken"이라는 이름을 사용해야 합니다.

커널 모드 드라이버의 호출의 경우 Windows Native System Services 루틴의 NtXxxZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

   
지원되는 최소 클라이언트 Windows XP
대상 플랫폼 유니버설
헤더 ntifs.h(Ntifs.h 포함)
라이브러리 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 규정 준수 규칙 HwStorPortProhibitedDDIs, PowerIrpDDis

추가 정보

ACL

IRP_MJ_CREATE

SECURITY_IMPERSONATION_LEVEL

SID

SID_AND_ATTRIBUTES

SeQueryInformationToken

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_INFORMATION_CLASS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_TYPE

TOKEN_USER

ZwSetInformationToken