Função ZwOpenThreadTokenEx (ntifs.h)

Artigo
03/08/2023

A rotina ZwOpenThreadTokenEx abre o token de acesso associado a um thread.

Sintaxe

NTSYSAPI NTSTATUS ZwOpenThreadTokenEx(
  [in]  HANDLE      ThreadHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  BOOLEAN     OpenAsSelf,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);

Parâmetros

[in] ThreadHandle

Manipule para o thread cujo token de acesso deve ser aberto. O identificador deve ter acesso THREAD_QUERY_INFORMATION. Use a macro NtCurrentThread para especificar o thread atual.

[in] DesiredAccess

ACCESS_MASK estrutura que especifica os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL (lista de controle de acesso discricionário) do token para determinar quais direitos de acesso são concedidos ou negados.

[in] OpenAsSelf

Valor booliano que especifica se o marcar de acesso deve ser feito no contexto de segurança do thread que está chamando ZwOpenThreadTokenEx ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, o marcar de acesso será executado usando o contexto de segurança para o thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, o marcar de acesso será feito usando o contexto de segurança do processo para o thread de chamada.

[in] HandleAttributes

Atributos para o identificador criado. No momento, há suporte apenas para OBJ_KERNEL_HANDLE. Se o chamador não estiver em execução no contexto do processo do sistema, ele deverá especificar OBJ_KERNEL_HANDLE para esse parâmetro.

[out] TokenHandle

Ponteiro para uma variável alocada pelo chamador que recebe um identificador para o token de acesso recém-aberto.

Retornar valor

ZwOpenThreadTokenEx retorna STATUS_SUCCESS ou um erro apropriado status. Possíveis códigos de status de erro incluem o seguinte:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	O ThreadHandle não tinha acesso THREAD_QUERY_INFORMATION.
STATUS_CANT_OPEN_ANONYMOUS	O cliente solicitou o nível de representação SecurityAnonymous. No entanto, um token anônimo não pode ser aberto. Para obter mais informações, consulte SECURITY_IMPERSONATION_LEVEL.
STATUS_INVALID_HANDLE	ThreadHandle não era um identificador válido.
STATUS_INVALID_PARAMETER	O HandleAttributes especificado não incluiu OBJ_KERNEL_HANDLE.
STATUS_NO_TOKEN	Foi feita uma tentativa de abrir um token associado a um thread que não está representando um cliente no momento.
STATUS_OBJECT_TYPE_MISMATCH	ThreadHandle não era um identificador de thread.

Comentários

ZwOpenThreadTokenEx abre o token de acesso associado a um thread e retorna um identificador para esse token.

O parâmetro OpenAsSelf permite que um processo de servidor abra o token de acesso para um processo de cliente quando o processo do cliente tiver especificado o nível de representação SecurityIdentification para o SECURITY_IMPERSONATION_LEVEL tipo enumerado. Sem esse parâmetro, o processo de chamada não pode abrir o token de acesso do cliente usando o contexto de segurança do cliente porque é impossível abrir objetos de nível executivo usando o nível de representação SecurityIdentification.

Qualquer identificador obtido chamando ZwOpenThreadTokenEx deve eventualmente ser liberado chamando ZwClose.

As rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o atributo OBJ_KERNEL_HANDLE para o parâmetro HandleAttributes de ZwOpenThreadTokenEx. Isso restringe o uso do identificador retornado por ZwOpenThreadTokenEx a processos em execução no modo kernel. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução.

Para obter mais informações sobre segurança e controle de acesso, consulte Modelo de segurança do Windows para desenvolvedores de driver e a documentação sobre esses tópicos no SDK do Windows.

Observação

Se a chamada para a função ZwOpenThreadTokenEx ocorrer no modo de usuário, você deverá usar o nome "NtOpenThreadTokenEx" em vez de "ZwOpenThreadTokenEx".

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 XP
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)