ZwQueryInformationToken 함수(ntifs.h)

아티클
12/21/2024

ZwQueryInformationToken 루틴은 액세스 토큰에 대한 지정된 유형의 정보를 검색합니다. 호출 프로세스에는 정보를 얻기 위한 적절한 액세스 권한이 있어야 합니다.

통사론

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [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 값 열에 나열됩니다.

[out] TokenInformation

토큰에 대한 요청된 정보를 수신하는 호출자 할당 버퍼에 대한 포인터입니다. 이 버퍼에 배치된 구조체는 다음 표와 같이 TokenInformationClass값에 따라 달라집니다. 모든 구조체는 32비트 경계에 맞춰야 합니다.

TokenInformationClass 값	TokenInformation 버퍼에 미치는 영향
TokenDefaultDacl	버퍼는 새로 만든 개체에 대한 기본 DACL 포함하는 TOKEN_DEFAULT_DACL 구조를 받습니다.
TokenGroups	버퍼는 토큰과 연결된 그룹 계정을 포함하는 TOKEN_GROUPS 구조를 받습니다.
TokenImpersonationLevel	버퍼는 토큰의 가장 수준을 나타내는 SECURITY_IMPERSONATION_LEVEL 값을 받습니다. 액세스 토큰이 가장 토큰이 아닌 경우 ZwQueryInformationToken 호출이 실패합니다.
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을 받습니다.

반환 값

ZwQueryInformationToken STATUS_SUCCESS 또는 적절한 오류 상태를 반환합니다. 가능한 오류 상태 코드에는 다음이 포함됩니다.

반환 코드	묘사
STATUS_ACCESS_DENIED	TokenHandle 필요한 액세스 권한이 없습니다.
STATUS_BUFFER_TOO_SMALL	요청된 토큰 정보 구조의 크기가 TokenInformationLength. 필요한 바이트 수는 returnLength반환됩니다.
STATUS_INVALID_HANDLE	TokenHandle 올바른 핸들이 아니었습니다.
STATUS_INVALID_INFO_CLASS	TokenInformationClass 유효한 토큰 정보 클래스가 아닙니다.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle 토큰 핸들이 아니었습니다.

발언

파일 시스템 또는 파일 시스템 필터 드라이버에서 ZwQueryInformationToken 루틴을 사용하여 IRP_MJ_CREATE 처리하는 동안 요청을 시작한 호출자의 SID 확인할 수 있습니다. ZwQueryInformationToken전달된 TokenInformationClass 매개 변수에 TokenUser 지정하면 TokenInformation 매개 변수가 가리키는 버퍼에 TOKEN_USER 구조가 반환됩니다. 이 반환된 버퍼에는 사용자 SID있는 SID_AND_ATTRIBUTES 구조체가 포함됩니다.

보안 및 액세스 제어에 대한 자세한 내용은 드라이버 개발자를 위한 Windows 보안 모델 및 Windows SDK의 이러한 항목에 대한 설명서를 참조하세요.

메모

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

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

요구 사항

요구	값
지원되는 최소 클라이언트	Windows XP
대상 플랫폼	보편적
헤더	ntifs.h(Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)