Функция ZwDuplicateToken (ntifs.h)
Функция ZwDuplicateToken создает дескриптор нового маркера доступа , который дублирует существующий маркер. Эта функция может создать первичный маркер или токен олицетворения.
Синтаксис
NTSYSAPI NTSTATUS ZwDuplicateToken(
[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
Битовая маска, указывающая запрошенные права доступа для нового маркера. ZwDuplicateToken сравнивает запрошенные права доступа с списком управления доступом существующего маркера (DACL), чтобы определить, какие права предоставляются или отказано в новом маркере. Чтобы запросить те же права доступа, что и существующий маркер, укажите ноль. Чтобы запросить все права доступа, допустимые для вызывающего абонента, укажите MAXIMUM_ALLOWED. Этот параметр является необязательным и может быть равен нулю, MAXIMUM_ALLOWED или побитовой комбинации ИЛИ одного или нескольких из следующих значений:
| Ценность | Значение |
|---|---|
| УДАЛИТЬ | Требуется для удаления объекта. |
| 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 Rights for Access-Token Objects в пакете SDK для Windows. Обратите внимание, что маркеры доступа не поддерживают право SYNCHRONIZE.
[in] ObjectAttributes
Указатель на структуру OBJECT_ATTRIBUTES, описывающую запрошенные свойства нового маркера. Параметр
Если параметр 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. В противном случае возвращается ZwDuplicateToken возвращается STATUS_BAD_IMPERSONATION_LEVEL. |
| TokenImpersonation | Новый токен — это токен олицетворения. Если существующий токен является маркером олицетворения, запрошенный уровень олицетворения (как указано в параметре ObjectAttributes) нового маркера, не должен быть больше уровня олицетворения существующего маркера. В противном случае ZwDuplicateToken возвращает STATUS_BAD_IMPERSONATION_LEVEL. |
Параметр tokenType
[out] NewTokenHandle
Указатель на выделенную вызывающей переменной типа HANDLE, которая получает дескриптор новому маркеру. Этот параметр является обязательным и не может иметь значение NULL.
Возвращаемое значение
ZwDuplicateToken возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные коды возврата ошибок включают следующие:
| Возвращаемый код | Описание |
|---|---|
| STATUS_ACCESS_VIOLATION | Произошло нарушение доступа к памяти. Например, если предыдущий режим был пользовательским и недопустимым объемом памяти пользовательского режима, ZwDuplicateToken возвращает STATUS_ACCESS_VIOLATION. |
| STATUS_INSUFFICIENT_RESOURCES | Не удалось выделить достаточную память для дублирования нового маркера. |
| STATUS_INVALID_PARAMETER | Обнаружен недопустимый параметр. |
| STATUS_BAD_IMPERSONATION_LEVEL | Запрошенный уровень олицетворения для нового токена больше, чем уровень олицетворения существующего токена. |
| STATUS_ACCESS_DENIED | ZwDuplicateToken возвращает STATUS_ACCESS_DENIED, если не удалось получить доступ к ExistingTokenHandle. Это произойдет, если существующий маркер не имеет права доступа TOKEN_DUPLICATE. |
| STATUS_INVALID_HANDLE | ZwDuplicateToken возвращает STATUS_INVALID_HANDLE, если ExistingTokenHandle ссылается на недопустимый дескриптор. |
Замечания
Если сведения олицетворения не были предоставлены параметром ObjectAttributes, уровень олицетворения существующего токена будет использоваться для нового маркера.
Что касается структуры, на которую указывает необязательный параметр ObjectAttributes, SecurityQualityOfServiceOBJECT_ATTRIBUTES указывает на структуру типа SECURITY_QUALITY_OF_SERVICE. Сведения о членах этой структуры см. в SECURITY_QUALITY_OF_SERVICE.
Элемент
Сведения об аналоговом режиме пользователя ZwDuplicateTokenсм. в дубликатаTokenEx.
Завершив использование нового маркера, вызовите функцию ZwClose, чтобы закрыть дескриптор маркера.
Если вызов функции ZwDuplicateToken происходит в пользовательском режиме, следует использовать имя "NtDuplicateToken" вместо "ZwDuplicateToken".
Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 |
| целевая платформа | Всеобщий |
| заголовка | ntifs.h (include Ntifs.h, FltKernel.h) |
| библиотеки |
NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI |