Función ZwDuplicateToken (ntifs.h)

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 obligatorio 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 valores siguientes:

Para obtener más información, vea Derechos de acceso para objetos de Access-Token en el 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 miembro SecurityDescriptor 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 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, consulte SECURITY_QUALITY_OF_SERVICE.

• Si el token existente es un token de suplantación y el parámetro ObjectAttributes no 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 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. El token resultante podría pasarse a un proceso secundario (CreateProcessAsUser), lo que restringiría lo que puede hacer el proceso secundario. Este parámetro es obligatorio.

[in] TokenType

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

El parámetro TokenType es necesario 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 obligatorio y no puede ser NULL.

Valor devuelto

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

Comentarios

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 ObjectAttributes opcional, 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 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 produce 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 versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar 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 NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Consulte también

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL