Função ZwDuplicateToken (ntifs.h)
A função ZwDuplicateToken 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
NTSYSAPI NTSTATUS ZwDuplicateToken(
[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. ZwDuplicateToken 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 |
| 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 no SDK do Windows. 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 TRUE, o chamador poderá duplicar um token, mas remover o grupo Administradores e o direito SeTcbPrivilege. 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 |
| |
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, ZwDuplicateToken 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
ZwDuplicateToken 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, ZwDuplicateToken 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 | ZwDuplicateToken retornará STATUS_ACCESS_DENIED se não puder acessar ExistingTokenHandle. Isso ocorreria se o token existente não tivesse o acesso TOKEN_DUPLICATE correto. |
| STATUS_INVALID_HANDLE | ZwDuplicateToken retornará STATUS_INVALID_HANDLE se ExistingTokenHandle se referir 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
O membro SecurityQualityOfService
Para obter informações sobre o análogo do modo de usuário de ZwDuplicateToken, consulte DuplicateTokenEx.
Quando terminar de usar o novo token, chame a função ZwClose para fechar o identificador de token.
Se a chamada para a função ZwDuplicateToken ocorrer no modo de usuário, você deverá usar o nome "NtDuplicateToken" em vez de "ZwDuplicateToken".
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(storport), PowerIrpDDis(wdm) |