Función DuplicateTokenEx (securitybaseapi.h)

Artículo
03/15/2023

La función DuplicateTokenEx crea 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

BOOL DuplicateTokenEx(
  [in]           HANDLE                       hExistingToken,
  [in]           DWORD                        dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES        lpTokenAttributes,
  [in]           SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
  [in]           TOKEN_TYPE                   TokenType,
  [out]          PHANDLE                      phNewToken
);

Parámetros

[in] hExistingToken

Identificador de un token de acceso abierto con TOKEN_DUPLICATE acceso.

[in] dwDesiredAccess

Especifica los derechos de acceso solicitados para el nuevo token. La función DuplicateTokenEx 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. 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.

Para obtener una lista de los derechos de acceso para los tokens de acceso, consulte Derechos de acceso para Access-Token Objetos.

[in, optional] lpTokenAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES que especifica un descriptor de seguridad para el nuevo token y determina si los procesos secundarios pueden heredar el token. Si lpTokenAttributes es NULL, el token obtiene un descriptor de seguridad predeterminado y el identificador no se puede heredar. Si el descriptor de seguridad contiene una lista de control de acceso del sistema (SACL), el token obtiene ACCESS_SYSTEM_SECURITY derecho de acceso, incluso si no se solicitó en dwDesiredAccess.

Para establecer el propietario en el descriptor de seguridad para el nuevo token, el token de proceso del autor de la llamada debe tener establecido el SE_RESTORE_NAME privilegios.

[in] ImpersonationLevel

Especifica un valor de la enumeración SECURITY_IMPERSONATION_LEVEL que indica el nivel de suplantación del nuevo token.

[in] TokenType

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

Valor	Significado
TokenPrimary	El nuevo token es un token principal que puede usar en la función CreateProcessAsUser .
TokenImpersonation	El nuevo token es un token de suplantación.

[out] phNewToken

Puntero a una variable HANDLE que recibe el nuevo token.

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

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función DuplicateTokenEx permite crear un token principal que puede usar en la función CreateProcessAsUser . Esto permite que una aplicación de servidor que suplanta a un cliente cree un proceso que tenga el contexto de seguridad del cliente. Tenga en cuenta que la función DuplicateToken solo puede crear tokens de suplantación, que no son válidos para CreateProcessAsUser.

A continuación se muestra un escenario típico para usar DuplicateTokenEx para crear un token principal. Una aplicación de servidor crea un subproceso que llama a una de las funciones de suplantación, como ImpersonateNamedPipeClient, para suplantar a un cliente. A continuación, el subproceso de suplantación llama a la función OpenThreadToken para obtener su propio token, que es un token de suplantación que tiene el contexto de seguridad del cliente. El subproceso especifica este token de suplantación en una llamada a DuplicateTokenEx, especificando la marca TokenPrimary. La función DuplicateTokenEx crea un token principal que tiene el contexto de seguridad del cliente.

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll