Função NtDuplicateToken (ntifs.h)
A função NtDuplicateToken cria um identificador para 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
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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
Um identificador para um token de acesso existente que foi aberto com o direito de acesso TOKEN_DUPLICATE. Esse parâmetro é necessário e não pode ser NULL.
[in] DesiredAccess
Bitmask que especifica os direitos de acesso solicitados para o novo token. NtDuplicateToken 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 ao novo token. 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. Esse parâmetro é opcional e pode ser zero, MAXIMUM_ALLOWED ou uma combinação OR bit a bit de um ou mais dos seguintes valores:
| Valor | Significado |
|---|---|
| DELETE | Necessário para excluir o objeto. |
| READ_CONTROL | Necessário para ler a DACL e as informações de propriedade do objeto. Para obter acesso à SACL (lista de controle de acesso do sistema), consulte ACCESS_SYSTEM_SECURITY posteriormente nesta tabela. |
| WRITE_DAC | Necessário para alterar as informações da DACL para o objeto . |
| WRITE_OWNER | Necessário para alterar as informações de propriedade no descritor de segurança do objeto (SECURITY_DESCRIPTOR). |
| ACCESS_SYSTEM_SECURITY | Necessário para obter ou definir o SACL na ACL de um objeto. O sistema operacional concede esse direito ao novo token somente se o privilégio SE_SECURITY_NAME estiver habilitado no token de acesso do thread de chamada. |
| STANDARD_RIGHTS_READ | Atualmente definido como igual a READ_CONTROL. |
| STANDARD_RIGHTS_WRITE | Atualmente definido como igual a READ_CONTROL. |
| STANDARD_RIGHTS_EXECUTE | Atualmente definido como igual a READ_CONTROL. |
| STANDARD_RIGHTS_REQUIRED | Combina o acesso DELETE, READ_CONTROL, WRITE_DAC e WRITE_OWNER. |
| STANDARD_RIGHTS_ALL | Combina o acesso DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER e SYNCHRONIZE. No entanto, o valor SYNCHRONIZE não é aplicável a objetos de token. Portanto, STANDARD_RIGHTS_ALL tem um funcionalmente equivalente a STANDARD_RIGHTS_REQUIRED. |
| TOKEN_ADJUST_DEFAULT | Necessário para alterar o proprietário padrão, o grupo primário ou a DACL de um token de acesso. |
| TOKEN_ADJUST_GROUPS | Necessário para ajustar os atributos dos grupos em um token de acesso. |
| TOKEN_ADJUST_PRIVILEGES | Necessário para habilitar ou desabilitar os privilégios em um token de acesso. |
| TOKEN_ADJUST_SESSIONID | Necessário para ajustar a SID (ID de sessão) de um token de acesso. O sistema operacional concede esse direito ao novo token somente se o privilégio SE_TCB_NAME estiver habilitado no token de acesso do thread de chamada. |
| TOKEN_ASSIGN_PRIMARY | Necessário para anexar um token primário a um processo. O sistema operacional concede esse direito ao novo token somente se o privilégio SE_ASSIGNPRIMARYTOKEN_NAME estiver habilitado no token de acesso do thread de chamada. |
| TOKEN_DUPLICATE | Necessário para duplicar um token de acesso. Observe que o token ExistingTokenHandle fornecido deve conter esse direito para usar essa rotina com êxito. |
| TOKEN_EXECUTE | Combina STANDARD_RIGHTS_EXECUTE e TOKEN_IMPERSONATE. |
| TOKEN_IMPERSONATE | Necessário para anexar um token de acesso de representação a um processo. |
| TOKEN_QUERY | Necessário para consultar um token de acesso. |
| TOKEN_QUERY_SOURCE | Necessário para consultar a origem de um token de acesso. |
| TOKEN_READ | Combina STANDARD_RIGHTS_READ e TOKEN_QUERY. |
| TOKEN_WRITE | Combina STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS e TOKEN_ADJUST_DEFAULT. |
| TOKEN_ALL_ACCESS | Combina todas as permissões de acesso de token possíveis para um token. |
Para obter informações adicionais, consulte Direitos de Acesso para objetos Access-Token. Observe que os tokens de acesso não dão suporte ao direito SYNCHRONIZE.
[in] ObjectAttributes
Ponteiro para uma estrutura OBJECT_ATTRIBUTES que descreve as propriedades solicitadas para o novo token. O parâmetro ObjectAttributes é opcional e pode ser NULL. Se o parâmetro ObjectAttributes for NULL ou se o membro SecurityDescriptor da estrutura apontada pelo parâmetro ObjectAttributes for NULL, o novo token receberá um descritor de segurança padrão e o novo identificador de token não poderá ser herdado. Nesse caso, esse descritor de segurança padrão é criado a partir do grupo de usuários, grupo primário e informações da DACL armazenadas no token do chamador.
Quando o parâmetro TokenType é definido como TokenImpersonation:
- O parâmetro ObjectAttributes pode ser usado para especificar o nível de representação do novo token. Isso pode ser feito definindo ObjectAttributes-SecurityQualityOfService.ImpersonationLevel >como um valor de enumeração SECURITY_IMPERSONATION_LEVEL apropriado. Para obter mais informações, consulte SECURITY_QUALITY_OF_SERVICE.
- Se o token existente for um token de representação e o parâmetro ObjectAttributes não fornecer informações de representação, o nível de representação do novo token será definido como o nível de representação do token existente.
- Se o token existente for um token primário e nenhuma informação de nível de representação for fornecida, o novo token de representação terá um SECURITY_IMPERSONATION_LEVEL nível de representação.
[in] EffectiveOnly
Um valor booliano que indica se todo o token existente deve ser duplicado no novo token ou apenas a parte efetiva (atualmente habilitada) do token. Se definido como TRUE, somente as partes habilitadas no momento do token de origem serão duplicadas. Se definido como FALSE, todo o token existente será duplicado. Isso fornece um meio para um chamador de um subsistema protegido limitar quais grupos e privilégios opcionais são disponibilizados para o subsistema protegido. Por exemplo, se EffectiveOnly for TRUE, o chamador poderá duplicar um token, mas remover o grupo Administradores e o seTcbPrivilege à direita. O token resultante poderia então ser passado para um processo filho (CreateProcessAsUser), o que restringiria o que o processo filho pode fazer. Este parâmetro é necessário.
[in] TokenType
Especifica um dos seguintes valores da enumeração TOKEN_TYPE .
| Valor | Significado |
|---|---|
| TokenPrimary | O novo token é um token primário. Se o token existente for um token de representação, o token de representação existente deverá ter um nível de representação (conforme fornecido pelo parâmetro ObjectAttributes ) de SecurityImpersonation ou SecurityDelegation. Caso contrário, NtDuplicateToken retornará STATUS_BAD_IMPERSONATION_LEVEL será retornado. |
| TokenImpersonation | O novo token é um token de representação. Se o token existente for um token de representação, o nível de representação solicitado (conforme fornecido pelo parâmetro ObjectAttributes ) do novo token não deverá ser maior que o nível de representação do token existente. Caso contrário, NtDuplicateToken retornará STATUS_BAD_IMPERSONATION_LEVEL. |
O parâmetro TokenType é necessário e não pode ser NULL.
[out] NewTokenHandle
Um ponteiro para uma variável alocada pelo chamador, do tipo HANDLE, que recebe um identificador para o novo token. Esse parâmetro é necessário e não pode ser NULL.
Retornar valor
NtDuplicateToken retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis códigos de retorno de erro incluem o seguinte:
| Código de retorno | Descrição |
|---|---|
| STATUS_ACCESS_VIOLATION | Ocorreu uma violação de acesso à memória. Por exemplo, se o modo anterior fosse modo de usuário e a memória inválida do modo de usuário fosse fornecida, NtDuplicateToken retornaria STATUS_ACCESS_VIOLATION. |
| STATUS_INSUFFICIENT_RESOURCES | Não foi possível alocar memória suficiente para duplicar o novo token. |
| STATUS_INVALID_PARAMETER | Um parâmetro inválido foi detectado. |
| STATUS_BAD_IMPERSONATION_LEVEL | O nível de representação solicitado para o novo token é maior que o nível de representação do token existente. |
| STATUS_ACCESS_DENIED | NtDuplicateToken não pôde acessar ExistingTokenHandle. Isso ocorrerá se o token existente não tiver o direito de acesso TOKEN_DUPLICATE. |
| STATUS_INVALID_HANDLE | ExistingTokenHandle refere-se a um identificador inválido. |
Comentários
Se nenhuma informação de nível de representação tiver sido fornecida pelo parâmetro ObjectAttributes , o nível de representação do token existente será usado para o novo token.
Em relação à estrutura apontada pelo parâmetro opcional ObjectAttributes , o membro SecurityQualityOfService do OBJECT_ATTRIBUTES aponta para uma estrutura do tipo SECURITY_QUALITY_OF_SERVICE. Consulte SECURITY_QUALITY_OF_SERVICE para obter informações sobre os membros dessa estrutura.
O membro SecurityQualityOfService deve ser definido depois de chamar a macro InitializeObjectAttributes porque InitializeObjectAttributes atualmente define SecurityQualityOfService como NULL.
Para obter informações sobre o analógico do modo de usuário de NtDuplicateToken, consulte DuplicateTokenEx na documentação do SDK do Windows.
Quando terminar de usar o novo token, chame a função NtClose para fechar o identificador de token.
Se a chamada para a função NtDuplicateToken ocorrer no modo de usuário, você deverá usar o nome "NtDuplicateToken" em vez de "NtDuplicateToken".
Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 |
| Plataforma de Destino | Universal |
| Cabeçalho | ntifs.h (include Ntifs.h, FltKernel.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de