Função DuplicateTokenEx (securitybaseapi.h)
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 |
|---|---|
|
O novo token é um token primário que você pode usar na função CreateProcessAsUser . |
|
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 |