Función ZwDuplicateToken (ntifs.h)

Artículo
12/21/2024

La función ZwDuplicateToken crea un identificador para un nuevo token de acceso que duplica un token existente. Esta función puede crear un token principal o un token de suplantación.

Sintaxis

NTSYSAPI NTSTATUS ZwDuplicateToken(
  [in]  HANDLE             ExistingTokenHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            EffectiveOnly,
  [in]  TOKEN_TYPE         TokenType,
  [out] PHANDLE            NewTokenHandle
);

Parámetros

[in] ExistingTokenHandle

Identificador de un token de acceso existente que se abrió con el derecho de acceso TOKEN_DUPLICATE. Este parámetro es necesario y no puede ser NULL.

[in] DesiredAccess

Máscara de bits que especifica los derechos de acceso solicitados para el nuevo token. ZwDuplicateToken compara los derechos de acceso solicitados con la lista de control de acceso discrecional (DACL) del token existente para determinar qué derechos se conceden o deniegan al nuevo token. Para solicitar los mismos derechos de acceso que el token existente, especifique cero. Para solicitar todos los derechos de acceso válidos para el autor de la llamada, especifique MAXIMUM_ALLOWED. Este parámetro es opcional y puede ser cero, MAXIMUM_ALLOWED o una combinación OR bit a bit de uno o varios de los siguientes valores:

Valor	Significado
BORRAR	Necesario para eliminar el objeto.
READ_CONTROL	Necesario para leer la INFORMACIÓN de propiedad y DACL del objeto. Para obtener acceso a la lista de control de acceso del sistema (SACL), consulte ACCESS_SYSTEM_SECURITY más adelante en esta tabla.
WRITE_DAC	Necesario para cambiar la información de DACL del objeto.
WRITE_OWNER	Necesario para cambiar la información de propiedad en el descriptor de seguridad del objeto (SECURITY_DESCRIPTOR).
ACCESS_SYSTEM_SECURITY	Necesario para obtener o establecer la SACL en la ACL de un objeto. El sistema operativo concede este derecho al nuevo token solo si el privilegio SE_SECURITY_NAME está habilitado en el token de acceso del subproceso que realiza la llamada.
STANDARD_RIGHTS_READ	Actualmente se define como igual a READ_CONTROL.
STANDARD_RIGHTS_WRITE	Actualmente se define como igual a READ_CONTROL.
STANDARD_RIGHTS_EXECUTE	Actualmente se define como igual a READ_CONTROL.
STANDARD_RIGHTS_REQUIRED	Combina el acceso DELETE, READ_CONTROL, WRITE_DAC y WRITE_OWNER.
STANDARD_RIGHTS_ALL	Combina EL acceso DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER y SYNCHRONIZE. Sin embargo, el valor SYNCHRONIZE no es aplicable a los objetos de token. Por lo tanto, STANDARD_RIGHTS_ALL tiene un valor funcionalmente equivalente a STANDARD_RIGHTS_REQUIRED.
TOKEN_ADJUST_DEFAULT	Necesario para cambiar el propietario predeterminado, el grupo principal o DACL de un token de acceso.
TOKEN_ADJUST_GROUPS	Necesario para ajustar los atributos de los grupos en un token de acceso.
TOKEN_ADJUST_PRIVILEGES	Necesario para habilitar o deshabilitar los privilegios en un token de acceso.
TOKEN_ADJUST_SESSIONID	Necesario para ajustar el identificador de sesión (SID) de un token de acceso. El sistema operativo concede este derecho al nuevo token solo si el SE_TCB_NAME privilegio está habilitado en el token de acceso del subproceso que realiza la llamada.
TOKEN_ASSIGN_PRIMARY	Necesario para adjuntar un token principal a un proceso. El sistema operativo concede este derecho al nuevo token solo si el privilegio SE_ASSIGNPRIMARYTOKEN_NAME está habilitado en el token de acceso del subproceso que realiza la llamada.
TOKEN_DUPLICATE	Necesario para duplicar un token de acceso. Tenga en cuenta que el token de existingTokenHandle especificado debe contener este derecho para poder usar correctamente esta rutina.
TOKEN_EXECUTE	Combina STANDARD_RIGHTS_EXECUTE y TOKEN_IMPERSONATE.
TOKEN_IMPERSONATE	Necesario para adjuntar un token de acceso de suplantación a un proceso.
TOKEN_QUERY	Necesario para consultar un token de acceso.
TOKEN_QUERY_SOURCE	Necesario para consultar el origen de un token de acceso.
TOKEN_READ	Combina STANDARD_RIGHTS_READ y TOKEN_QUERY.
TOKEN_WRITE	Combina STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS y TOKEN_ADJUST_DEFAULT.
TOKEN_ALL_ACCESS	Combina todos los permisos de acceso a tokens posibles para un token.

Para obtener más información, consulte Derechos de acceso para Access-Token Objetos en Windows SDK. Tenga en cuenta que los tokens de acceso no admiten el derecho SYNCHRONIZE.

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que describe las propiedades solicitadas para el nuevo token. El parámetro ObjectAttributes es opcional y puede ser NULL. Si el parámetro ObjectAttributes es NULL o si el SecurityDescriptor miembro de la estructura a la que apunta el parámetro ObjectAttributes es NULL, el nuevo token recibe un descriptor de seguridad predeterminado y el nuevo identificador de token no se puede heredar. En ese caso, este descriptor de seguridad predeterminado se crea a partir del grupo de usuarios, el grupo principal y la información de DACL que se almacena en el token del autor de la llamada.

Cuando el parámetro tokenType de se establece en tokenImpersonation:

El parámetro ObjectAttributes se puede usar para especificar el nivel de suplantación del nuevo token. Esto se puede lograr estableciendo ObjectAttributes:>SecurityQualityOfService.ImpersonationLevel en un valor de enumeración SECURITY_IMPERSONATION_LEVEL adecuado. Para obtener más información, vea SECURITY_QUALITY_OF_SERVICE.
Si el token existente es un token de suplantación y el parámetro ObjectAttributes proporciona información de suplantación, el nivel de suplantación del nuevo token se establece en el nivel de suplantación del token existente.
Si el token existente es un token principal y no se proporciona información de nivel de suplantación, el nuevo token de suplantación tendrá un nivel de suplantación SECURITY_IMPERSONATION_LEVEL.

[in] EffectiveOnly

Valor booleano que indica si todo el token existente debe duplicarse en el nuevo token o solo en la parte efectiva (actualmente habilitada) del token. Si se establece en TRUE, solo se duplicarán las partes habilitadas actualmente del token de origen. Si se establece en FALSE, se duplicará todo el token existente. Esto proporciona un medio para que un autor de la llamada de un subsistema protegido limite los grupos y privilegios opcionales que están disponibles para el subsistema protegido. Por ejemplo, si EffectiveOnly es TRUE, el autor de la llamada podría duplicar un token, pero quitar el grupo Administradores y el derecho SeTcbPrivilege. A continuación, el token resultante podría pasarse a un proceso secundario (CreateProcessAsUser), lo que restringiría lo que el proceso secundario puede hacer. Este parámetro es obligatorio.

[in] TokenType

Especifica uno de los siguientes valores de la enumeración TOKEN_TYPE.

Valor	Significado
tokenPrimary	El nuevo token es un token principal. Si el token existente es un token de suplantación, el token de suplantación existente debe tener un nivel de suplantación (tal como lo proporciona el parámetro ObjectAttributes) de SecurityImpersonation o SecurityDelegation. De lo contrario, se devuelve STATUS_BAD_IMPERSONATION_LEVEL ZwDuplicateToken.
tokenImpersonation	El nuevo token es un token de suplantación. Si el token existente es un token de suplantación, el nivel de suplantación solicitado (tal como lo proporciona el parámetro ObjectAttributes ) del nuevo token no debe ser mayor que el nivel de suplantación del token existente. De lo contrario, zwDuplicateToken devuelve STATUS_BAD_IMPERSONATION_LEVEL.

Se requiere el parámetro TokenType y no puede ser NULL.

[out] NewTokenHandle

Puntero a una variable asignada por el autor de la llamada, de tipo HANDLE, que recibe un identificador para el nuevo token. Este parámetro es necesario y no puede ser NULL.

Valor devuelto

ZwDuplicateToken devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los códigos de retorno de error posibles se incluyen los siguientes:

Código devuelto	Descripción
STATUS_ACCESS_VIOLATION	Se ha producido una infracción de acceso a la memoria. Por ejemplo, si el modo anterior era modo de usuario y se proporcionó memoria en modo de usuario no válida, zwDuplicateToken devuelve STATUS_ACCESS_VIOLATION.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar memoria suficiente para duplicar el nuevo token.
STATUS_INVALID_PARAMETER	Se detectó un parámetro no válido.
STATUS_BAD_IMPERSONATION_LEVEL	El nivel de suplantación solicitado para el nuevo token es mayor que el nivel de suplantación del token existente.
STATUS_ACCESS_DENIED	ZwDuplicateToken devuelve STATUS_ACCESS_DENIED si no pudo acceder a ExistingTokenHandle. Esto ocurriría si el token existente no tiene el derecho de acceso TOKEN_DUPLICATE.
STATUS_INVALID_HANDLE	zwDuplicateToken devuelve STATUS_INVALID_HANDLE si ExistingTokenHandle hace referencia a un identificador no válido.

Observaciones

Si el parámetro ObjectAttributes no proporcionó información de nivel de suplantación, el nivel de suplantación del token existente se usará para el nuevo token.

Con respecto a la estructura a la que apunta el parámetro opcional ObjectAttributes, el miembro SecurityQualityOfService de OBJECT_ATTRIBUTES apunta a una estructura de tipo SECURITY_QUALITY_OF_SERVICE. Consulte SECURITY_QUALITY_OF_SERVICE para obtener información sobre los miembros de esta estructura.

El miembro SecurityQualityOfService debe establecerse después de llamar a la macro de InitializeObjectAttributes porque InitializeObjectAttributes establece actualmente SecurityQualityOfService en NULL.

Para obtener información sobre la analogía en modo de usuario de ZwDuplicateToken, vea DuplicateTokenEx.

Cuando haya terminado de usar el nuevo token, llame a la función ZwClose para cerrar el identificador del token.

Si la llamada a la función ZwDuplicateToken se realiza en modo de usuario, debe usar el nombre "NtDuplicateToken" en lugar de "ZwDuplicateToken".

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h, FltKernel.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Consulte también

ACCESS_MASK

initializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL

Compartir a través de