Función DuplicateTokenEx (securitybaseapi.h)

Artículo
11/20/2024

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

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 acceso TOKEN_DUPLICATE.

[in] dwDesiredAccess

Especifica los derechos de acceso solicitados para el nuevo token. La función DuplicateTokenEx compara los derechos de acceso solicitados con el lista de control de acceso discrecional del token existente (DACL) 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 Objects.

[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 un 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 del nuevo token, el token de proceso del autor de la llamada debe tener establecido el privilegio SE_RESTORE_NAME.

[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 siguientes valores de la enumeración TOKEN_TYPE.

Valor	Significado
tokenPrimary	El nuevo token es un token principal que puede usar en la función CreateProcessAsUser de .
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.

Observaciones

La función DuplicateTokenEx permite crear un token principal que puede usar en la función CreateProcessAsUser de . 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 de . 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

Requisito	Valor
cliente mínimo admitido	Windows XP [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	securitybaseapi.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll