NtDuplicateToken 함수(ntifs.h)
NtDuplicateToken 함수는 기존 토큰을 복제하는 새 액세스 토큰에 대한 핸들을 만듭니다. 이 함수는 기본 토큰 또는 가장 토큰을 만들 수 있습니다.
구문
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[in] HANDLE ExistingTokenHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN EffectiveOnly,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE NewTokenHandle
);
매개 변수
[in] ExistingTokenHandle
TOKEN_DUPLICATE 액세스 권한으로 열린 기존 액세스 토큰에 대한 핸들입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.
[in] DesiredAccess
새 토큰에 대해 요청된 액세스 권한을 지정하는 비트 마스크입니다. NtDuplicateToken 은 요청된 액세스 권한을 기존 토큰의 DACL(임의 액세스 제어 목록)과 비교하여 새 토큰에 부여되거나 거부된 권한을 결정합니다. 기존 토큰과 동일한 액세스 권한을 요청하려면 0을 지정합니다. 호출자에게 유효한 모든 액세스 권한을 요청하려면 MAXIMUM_ALLOWED 지정합니다. 이 매개 변수는 선택 사항이며 0, MAXIMUM_ALLOWED 또는 다음 값 중 하나 이상의 비트 OR 조합일 수 있습니다.
값 | 의미 |
---|---|
DELETE | 개체를 삭제하는 데 필요합니다. |
READ_CONTROL | 개체에 대한 DACL 및 소유권 정보를 읽는 데 필요합니다. SACL(시스템 액세스 제어 목록)에 대한 액세스는 이 표의 뒷부분에 있는 ACCESS_SYSTEM_SECURITY 참조하세요. |
WRITE_DAC | 개체에 대한 DACL 정보를 변경하는 데 필요합니다. |
WRITE_OWNER | 개체의 보안 설명자(SECURITY_DESCRIPTOR)에서 소유권 정보를 변경하는 데 필요합니다. |
ACCESS_SYSTEM_SECURITY | 개체의 ACL에서 SACL을 가져오기 또는 설정하는 데 필요합니다. 운영 체제는 호출 스레드의 액세스 토큰에서 SE_SECURITY_NAME 권한이 활성화된 경우에만 새 토큰에 이 권한을 부여합니다. |
STANDARD_RIGHTS_READ | 현재 같음 READ_CONTROL 정의됩니다. |
STANDARD_RIGHTS_WRITE | 현재 같음 READ_CONTROL 정의됩니다. |
STANDARD_RIGHTS_EXECUTE | 현재 같음 READ_CONTROL 정의됩니다. |
STANDARD_RIGHTS_REQUIRED | DELETE, READ_CONTROL, WRITE_DAC 및 WRITE_OWNER 액세스를 결합합니다. |
STANDARD_RIGHTS_ALL | DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER 및 SYNCHRONIZE 액세스를 결합합니다. 그러나 SYNCHRONIZE 값은 토큰 개체에 적용할 수 없습니다. 따라서 STANDARD_RIGHTS_ALL STANDARD_RIGHTS_REQUIRED 기능적으로 동일합니다. |
TOKEN_ADJUST_DEFAULT | 액세스 토큰의 기본 소유자, 기본 그룹 또는 DACL을 변경하는 데 필요합니다. |
TOKEN_ADJUST_GROUPS | 액세스 토큰에서 그룹의 특성을 조정하는 데 필요합니다. |
TOKEN_ADJUST_PRIVILEGES | 액세스 토큰에서 권한을 사용하거나 사용하지 않도록 설정하는 데 필요합니다. |
TOKEN_ADJUST_SESSIONID | 액세스 토큰의 SID(세션 ID)를 조정하는 데 필요합니다. 운영 체제는 호출 스레드의 액세스 토큰에서 SE_TCB_NAME 권한이 활성화된 경우에만 새 토큰에 이 권한을 부여합니다. |
TOKEN_ASSIGN_PRIMARY | 프로세스에 기본 토큰을 연결하는 데 필요합니다. 운영 체제는 호출 스레드의 액세스 토큰에서 SE_ASSIGNPRIMARYTOKEN_NAME 권한이 활성화된 경우에만 새 토큰에 이 권한을 부여합니다. |
TOKEN_DUPLICATE | 액세스 토큰을 복제하는 데 필요합니다. 이 루틴을 성공적으로 사용하려면 지정된 ExistingTokenHandle 토큰에 이 권한이 포함되어야 합니다. |
TOKEN_EXECUTE | STANDARD_RIGHTS_EXECUTE 및 TOKEN_IMPERSONATE 결합합니다. |
TOKEN_IMPERSONATE | 프로세스에 가장 액세스 토큰을 연결하는 데 필요합니다. |
TOKEN_QUERY | 액세스 토큰을 쿼리하는 데 필요합니다. |
TOKEN_QUERY_SOURCE | 액세스 토큰의 원본을 쿼리하는 데 필요합니다. |
TOKEN_READ | STANDARD_RIGHTS_READ 및 TOKEN_QUERY 결합합니다. |
TOKEN_WRITE | STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS 및 TOKEN_ADJUST_DEFAULT 결합합니다. |
TOKEN_ALL_ACCESS | 토큰에 대해 가능한 모든 토큰 액세스 권한을 결합합니다. |
자세한 내용은 Access-Token 개체에 대한 액세스 권한을 참조하세요. 액세스 토큰은 SYNCHRONIZE 권한을 지원하지 않습니다.
[in] ObjectAttributes
새 토큰에 대해 요청된 속성을 설명하는 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. ObjectAttributes 매개 변수는 선택 사항이며 NULL일 수 있습니다. ObjectAttributes 매개 변수가 NULL이거나 ObjectAttributes 매개 변수가 가리키는 구조체의 SecurityDescriptor 멤버가 NULL인 경우 새 토큰은 기본 보안 설명자를 수신하며 새 토큰 핸들을 상속할 수 없습니다. 이 경우 이 기본 보안 설명자는 호출자의 토큰에 저장된 사용자 그룹, 기본 그룹 및 DACL 정보에서 만들어집니다.
TokenType 매개 변수가 TokenImpersonation으로 설정된 경우:
- ObjectAttributes 매개 변수를 사용하여 새 토큰의 가장 수준을 지정할 수 있습니다. 이 작업은 ObjectAttributes-SecurityQualityOfService.ImpersonationLevel>을 적절한 SECURITY_IMPERSONATION_LEVEL 열거형 값으로 설정하여 수행할 수 있습니다. 자세한 내용은 SECURITY_QUALITY_OF_SERVICE 참조하세요.
- 기존 토큰이 가장 토큰이고 ObjectAttributes 매개 변수가 가장 정보를 제공하지 않는 경우 새 토큰의 가장 수준은 기존 토큰의 가장 수준으로 설정됩니다.
- 기존 토큰이 기본 토큰이고 가장 수준 정보가 제공되지 않는 경우 새 가장 토큰에는 SECURITY_IMPERSONATION_LEVEL 가장 수준이 있습니다.
[in] EffectiveOnly
전체 기존 토큰을 새 토큰에 복제할지 아니면 토큰의 유효(현재 사용) 부분만 복제해야 하는지를 나타내는 부울 값입니다. TRUE로 설정하면 원본 토큰의 현재 활성화된 부분만 중복됩니다. FALSE로 설정하면 기존 토큰 전체가 중복됩니다. 이렇게 하면 보호된 하위 시스템의 호출자가 보호된 하위 시스템에 사용할 수 있는 선택적 그룹 및 권한을 제한할 수 있습니다. 예를 들어 EffectiveOnly 가 TRUE인 경우 호출자는 토큰을 복제할 수 있지만 Administrators 그룹과 SeTcbPrivilege 권한을 제거할 수 있습니다. 그런 다음 결과 토큰을 자식 프로세스(CreateProcessAsUser)에 전달하여 자식 프로세스에서 수행할 수 있는 작업을 제한할 수 있습니다. 이 매개 변수는 필수입니다.
[in] TokenType
TOKEN_TYPE 열거형에서 다음 값 중 하나를 지정합니다.
값 | 의미 |
---|---|
TokenPrimary | 새 토큰은 기본 토큰입니다. 기존 토큰이 가장 토큰인 경우 기존 가장 토큰에는 SecurityImpersonation 또는 SecurityDelegation의 가장 수준(ObjectAttributes 매개 변수에서 제공됨)이 있어야 합니다. 그렇지 않으면 NtDuplicateToken 은 반환되는 STATUS_BAD_IMPERSONATION_LEVEL 반환합니다. |
TokenImpersonation | 새 토큰은 가장 토큰입니다. 기존 토큰이 가장 토큰인 경우 새 토큰의 요청된 가장 수준( ObjectAttributes 매개 변수에서 제공됨)이 기존 토큰의 가장 수준보다 크지 않아야 합니다. 그렇지 않으면 NtDuplicateToken 은 STATUS_BAD_IMPERSONATION_LEVEL 반환합니다. |
TokenType 매개 변수는 필수이며 NULL일 수 없습니다.
[out] NewTokenHandle
새 토큰에 대한 핸들을 수신하는 HANDLE 형식의 호출자 할당 변수에 대한 포인터입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.
반환 값
NtDuplicateToken 은 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 코드에는 다음이 포함됩니다.
반환 코드 | 설명 |
---|---|
STATUS_ACCESS_VIOLATION | 메모리 액세스 위반이 발생했습니다. 예를 들어 이전 모드가 사용자 모드이고 잘못된 사용자 모드 메모리가 제공된 경우 NtDuplicateToken 은 STATUS_ACCESS_VIOLATION 반환합니다. |
STATUS_INSUFFICIENT_RESOURCES | 새 토큰을 복제하기 위해 충분한 메모리를 할당할 수 없습니다. |
STATUS_INVALID_PARAMETER | 잘못된 매개 변수가 감지되었습니다. |
STATUS_BAD_IMPERSONATION_LEVEL | 새 토큰에 대해 요청된 가장 수준이 기존 토큰의 가장 수준보다 큽습니다. |
STATUS_ACCESS_DENIED | NtDuplicateToken 이 ExistingTokenHandle에 액세스할 수 없습니다. 이 문제는 기존 토큰에 TOKEN_DUPLICATE 액세스 권한이 없는 경우에 발생합니다. |
STATUS_INVALID_HANDLE | ExistingTokenHandle 은 잘못된 핸들을 나타냅니다. |
설명
ObjectAttributes 매개 변수에서 가장 수준 정보를 제공하지 않은 경우 기존 토큰의 가장 수준이 새 토큰에 사용됩니다.
선택적 ObjectAttributes 매개 변수가 가리키는 구조체와 관련하여 OBJECT_ATTRIBUTESSecurityQualityOfService 멤버는 SECURITY_QUALITY_OF_SERVICE 형식의 구조를 가리킵니다. 이 구조체의 멤버에 대한 자세한 내용은 SECURITY_QUALITY_OF_SERVICE 참조하세요.
InitializeObjectAttributes는 현재 SecurityQualityOfService를 NULL로 설정하므로 InitializeObjectAttributes 매크로를 호출한 후SecurityQualityOfService 멤버를 설정해야 합니다.
NtDuplicateToken의 사용자 모드 아날로그에 대한 자세한 내용은 Windows SDK 설명서의 DuplicateTokenEx를 참조하세요.
새 토큰 사용을 마쳤으면 NtClose 함수를 호출하여 토큰 핸들을 닫습니다.
NtDuplicateToken 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "NtDuplicateToken" 대신 "NtDuplicateToken"이라는 이름을 사용해야 합니다.
커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Windows 2000 |
대상 플랫폼 | 유니버설 |
헤더 | ntifs.h(Ntifs.h, FltKernel.h 포함) |
라이브러리 | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL |
DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs, PowerIrpDDis |