Função DuplicateTokenEx (securitybaseapi.h)

Artigo
08/25/2023

A função DuplicateTokenEx cria um novo token de acesso que duplica um token existente. Essa função pode criar um token primário ou um token de representação.

Sintaxe

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

Um identificador para um token de acesso aberto com acesso TOKEN_DUPLICATE.

[in] dwDesiredAccess

Especifica os direitos de acesso solicitados para o novo token. A função DuplicateTokenEx compara os direitos de acesso solicitados com a DACL ( lista de controle de acesso discricionário ) do token existente para determinar quais direitos são concedidos ou negados. Para solicitar os mesmos direitos de acesso que o token existente, especifique zero. Para solicitar todos os direitos de acesso válidos para o chamador, especifique MAXIMUM_ALLOWED.

Para obter uma lista de direitos de acesso para tokens de acesso, consulte Direitos de acesso para objetos Access-Token.

[in, optional] lpTokenAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo token e determina se os processos filho podem herdar o token. Se lpTokenAttributes for NULL, o token obterá um descritor de segurança padrão e o identificador não poderá ser herdado. Se o descritor de segurança contiver uma SACL ( lista de controle de acesso do sistema ), o token obterá ACCESS_SYSTEM_SECURITY direito de acesso, mesmo que não tenha sido solicitado em dwDesiredAccess.

Para definir o proprietário no descritor de segurança para o novo token, o token de processo do chamador deve ter o SE_RESTORE_NAME privilégio definido.

[in] ImpersonationLevel

Especifica um valor da enumeração SECURITY_IMPERSONATION_LEVEL que indica o nível de representação do novo token.

[in] TokenType

Especifica um dos seguintes valores da enumeração TOKEN_TYPE .

Valor	Significado
TokenPrimary	O novo token é um token primário que você pode usar na função CreateProcessAsUser .
TokenImpersonation	O novo token é um token de representação.

[out] phNewToken

Um ponteiro para uma variável HANDLE que recebe o novo token.

Quando terminar de usar o novo token, chame a função CloseHandle para fechar o identificador de token.

Valor retornado

Se a função for bem-sucedida, a função retornará um valor diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função DuplicateTokenEx permite que você crie um token primário que pode ser usado na função CreateProcessAsUser . Isso permite que um aplicativo de servidor que representa um cliente crie um processo que tenha o contexto de segurança do cliente. Observe que a função DuplicateToken pode criar apenas tokens de representação, que não são válidos para CreateProcessAsUser.

Veja a seguir um cenário típico para usar DuplicateTokenEx para criar um token primário. Um aplicativo de servidor cria um thread que chama uma das funções de representação, como ImpersonateNamedPipeClient, para representar um cliente. O thread de representação chama a função OpenThreadToken para obter seu próprio token, que é um token de representação que tem o contexto de segurança do cliente. O thread especifica esse token de representação em uma chamada para DuplicateTokenEx, especificando o sinalizador TokenPrimary. A função DuplicateTokenEx cria um token primário que tem o contexto de segurança do cliente.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll