Função NtOpenThreadTokenEx (ntifs.h)

Artigo
02/26/2024

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

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenThreadTokenEx(
  [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 solicitados de acesso 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 chama NtOpenThreadTokenEx 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. Somente OBJ_KERNEL_HANDLE tem suporte no momento. 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

NtOpenThreadTokenEx retorna STATUS_SUCCESS ou um erro apropriado status. Os 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 representa um cliente no momento.
STATUS_OBJECT_TYPE_MISMATCH	ThreadHandle não era um identificador de thread.

Comentários

NtOpenThreadTokenEx 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 tipo enumerado SECURITY_IMPERSONATION_LEVEL . Sem esse parâmetro, o processo de chamada não é capaz de 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 NtOpenThreadTokenEx deve eventualmente ser liberado chamando NtClose.

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 NtOpenThreadTokenEx. Isso restringe o uso do identificador retornado por NtOpenThreadTokenEx aos 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.

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do 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 dos Serviços de Sistema Nativo.

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 de DDI	HwStorPortProhibitedDIs, PowerIrpDDis