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 TOKEN_DUPLICATE direito de acesso. Esse parâmetro é necessário e não pode ser NULL.
[in] DesiredAccess
Máscara de bits 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 |
|---|---|
| EXCLUIR | 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 acesso DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER e SYNCHRONIZE. No entanto, o valor SYNCHRONIZE não é aplicável a objetos de token. Assim, STANDARD_RIGHTS_ALL tem um equivalente funcional 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 da 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 com êxito essa rotina. |
| 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 Access Rights for Access-Token Objects. 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 SecurityDescriptor membro da estrutura apontado 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 com base nas informações de grupo de usuários, grupo primário e 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 para 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 nível de representação SECURITY_IMPERSONATION_LEVEL.
[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 atualmente habilitadas 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 opcionais e privilégios são disponibilizados para o subsistema protegido. Por exemplo, se EffectiveOnly for verdadeiro, 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. Esse 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 retorna STATUS_BAD_IMPERSONATION_LEVEL é 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 do 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 por chamador, do tipo HANDLE, que recebe um identificador para o novo token. Esse parâmetro é necessário e não pode ser NULL.
Valor de retorno
NtDuplicateToken retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os códigos de retorno de erro possíveis 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 era o modo de usuário e a memória inválida do modo de usuário foi fornecida, NtDuplicateToken retornará 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 do que o nível de representação do token existente. |
| STATUS_ACCESS_DENIED | NtDuplicateToken não pôde acessar ExistingTokenHandle. Isso ocorreria se o token existente não tivesse o acesso TOKEN_DUPLICATE correto. |
| STATUS_INVALID_HANDLE | ExistingTokenHandle refere-se a um identificador inválido. |
Observações
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 de 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 após chamar a macroInitializeObjectAttributesporque InitializeObjectAttributes atualmente define SecurityQualityOfService como NULL.
Para obter informações sobre o análogo 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 no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows 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 Usando versões Nt e Zw das rotinas de serviços do sistema nativo.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 |
| da Plataforma de Destino | Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h, FltKernel.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |