Функция 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) маркера, чтобы определить, какие права предоставляются или запрещаются новому маркеру. Чтобы запросить те же права доступа, что и у существующего маркера, укажите ноль. Чтобы запросить все права доступа, действительные для вызывающей стороны, укажите MAXIMUM_ALLOWED. Этот параметр является необязательным и может быть равен нулю, MAXIMUM_ALLOWED или побитовой комбинации ИЛИ из одного или нескольких следующих значений:
| Значение | Значение |
|---|---|
| DELETE | Требуется для удаления объекта . |
| READ_CONTROL | Требуется для чтения DACL и сведений о владельце для объекта. Сведения о доступе к списку управления доступом системы (SACL) см. в разделе ACCESS_SYSTEM_SECURITY далее в этой таблице. |
| WRITE_DAC | Требуется для изменения сведений DACL для объекта . |
| WRITE_OWNER | Требуется для изменения сведений о владельцах в дескрипторове безопасности объекта (SECURITY_DESCRIPTOR). |
| ACCESS_SYSTEM_SECURITY | Требуется для получения или задания saCL в ACL объекта. Операционная система предоставляет это право новому маркеру только в том случае, если в маркере доступа вызывающего потока включена привилегия 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) маркера доступа. Операционная система предоставляет это право новому маркеру, только если в маркере доступа вызывающего потока включена привилегия 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 или элемент SecurityDescriptor структуры, на который указывает параметр ObjectAttributes , равен 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, вызывающий объект может дублировать маркер, но удалить группу Администраторы и право SeTcbPrivilege. Полученный маркер затем может быть передан дочернему процессу (CreateProcessAsUser), что ограничит возможности дочернего процесса. Это обязательный параметр.
[in] TokenType
Задает одно из следующих значений перечисления TOKEN_TYPE .
| Значение | Значение |
|---|---|
| TokenPrimary | Новый маркер является основным. Если существующий маркер является маркером олицетворения, существующий маркер олицетворения должен иметь уровень олицетворения (как указано в параметре ObjectAttributes ) объекта SecurityImpersonation или SecurityDelegation. В противном случае 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 , то элемент SecurityQualityOfServiceOBJECT_ATTRIBUTES указывает на структуру типа SECURITY_QUALITY_OF_SERVICE. Сведения о членах этой структуры см. в разделе SECURITY_QUALITY_OF_SERVICE .
Элемент SecurityQualityOfService должен быть задан после вызова макроса InitializeObjectAttributes , так как InitializeObjectAttributes в настоящее время присваивает securityQualityOfService значение NULL.
Сведения об аналоге NtDuplicateToken в пользовательском режиме см. в разделе DuplicateTokenEx документации по Windows SDK.
Завершив использование нового маркера, вызовите функцию NtClose , чтобы закрыть дескриптор маркера.
Если вызов функции NtDuplicateToken выполняется в пользовательском режиме, следует использовать имя "NtDuplicateToken" вместо "NtDuplicateToken".
Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы Собственные системные службы Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 |
| Целевая платформа | Универсальное |
| Верхняя часть | ntifs.h (включая Ntifs.h, FltKernel.h) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Правила соответствия DDI | HwStorPortProhibitedDIs, PowerIrpDDis |