Função ZwQueryInformationToken (ntifs.h)

Artigo
12/21/2024

A rotina de ZwQueryInformationToken recupera um tipo de informação especificado sobre um token de acesso. O processo de chamada deve ter direitos de acesso apropriados para obter as informações.

Sintaxe

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Parâmetros

[in] TokenHandle

Manipule um token de acesso do qual as informações devem ser recuperadas. Se TokenInformationClass estiver definido como TokenSource, o identificador deverá ter acesso TOKEN_QUERY_SOURCE. Para todos os outros valores TokenInformationClass , o identificador deve ter acesso TOKEN_QUERY. Para obter mais informações sobre direitos de acesso para objetos de token de acesso, consulte a seção Segurança da documentação do SDK do Windows.

[in] TokenInformationClass

Um valor do tipo TOKEN_INFORMATION_CLASS enumerado que identifica o tipo de informação a ser recuperada. Os valores possíveis para esse parâmetro são listados na coluna TokenInformationClass Value da tabela mostrada na descrição do parâmetro TokenInformation.

[out] TokenInformation

Ponteiro para um buffer alocado por chamador que recebe as informações solicitadas sobre o token. A estrutura colocada nesse buffer depende do valor de TokenInformationClass, conforme mostrado na tabela a seguir. Todas as estruturas devem ser alinhadas em um limite de 32 bits.

Valor de TokenInformationClass	Efeito no buffer TokenInformation
TokenDefaultDacl	O buffer recebe uma estrutura TOKEN_DEFAULT_DACL que contém o DACL de padrão para objetos recém-criados.
TokenGroups	O buffer recebe uma estrutura TOKEN_GROUPS que contém as contas de grupo associadas ao token.
TokenImpersonationLevel	O buffer recebe um valor SECURITY_IMPERSONATION_LEVEL indicando o nível de representação do token. Se o token de acesso não for um token de representação, a chamada para ZwQueryInformationToken falhará.
TokenOwner	O buffer recebe uma estrutura TOKEN_OWNER que contém o proprietário padrão sid para objetos recém-criados.
TokenPrimaryGroup	O buffer recebe uma estrutura TOKEN_PRIMARY_GROUP que contém o SID do grupo primário padrão para objetos recém-criados.
TokenPrivileges	O buffer recebe uma estrutura TOKEN_PRIVILEGES que contém os privilégios do token.
TokenSessionId	O buffer recebe um valor de 32 bits especificando o identificador de sessão dos Serviços de Terminal associado ao token. Se o token estiver associado à sessão de console do Terminal Server, o identificador de sessão será zero. Um identificador de sessão diferente de zero indica uma sessão de cliente dos Serviços de Terminal. Em um ambiente de Serviços não Terminais, o identificador de sessão é zero.
TokenSource	O buffer recebe uma estrutura de TOKEN_SOURCE que contém a origem do token. TOKEN_QUERY_SOURCE acesso é necessário para recuperar essas informações.
tokenStatistics	O buffer recebe uma estrutura de TOKEN_STATISTICS que contém várias estatísticas de token.
TokenType	O buffer recebe um valor TOKEN_TYPE indicando se o token é um token primário ou de representação.
do TokenUser	O buffer recebe uma estrutura de TOKEN_USER que contém a conta de usuário do token.

[in] TokenInformationLength

Comprimento, em bytes, do buffer TokenInformation alocado pelo chamador.

[out] ReturnLength

Ponteiro para uma variável alocada por chamador que recebe o comprimento real, em bytes, das informações retornadas no buffer TokenInformation . Se qualquer uma das seguintes condições for verdadeira, nenhum dado será retornado no buffer TokenInformation :

O tamanho da estrutura de informações de token solicitada é maior que TokenInformationLength. Nesse caso, ReturnLength recebe o número real de bytes necessários para armazenar as informações solicitadas.
O valor de TokenInformationClass é TokenDefaultDacl e não há nenhum DACL padrão estabelecido para o token. Nesse caso, ReturnLength recebe zero.

Valor de retorno

ZwQueryInformationToken retorna STATUS_SUCCESS ou um status de erro apropriado. Os códigos de status de erro possíveis incluem o seguinte:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	TokenHandle não tinha o acesso necessário.
STATUS_BUFFER_TOO_SMALL	O tamanho da estrutura de informações de token solicitada é maior que TokenInformationLength. O número de bytes necessários é retornado no ReturnLength.
STATUS_INVALID_HANDLE	tokenHandle não era um identificador válido.
STATUS_INVALID_INFO_CLASS	TokenInformationClass não era uma classe de informações de token válida.
STATUS_OBJECT_TYPE_MISMATCH	tokenHandle não era um identificador de token.

Observações

A rotina de ZwQueryInformationToken pode ser usada por um sistema de arquivos ou driver de filtro do sistema de arquivos para determinar o SID do chamador que iniciou a solicitação durante IRP_MJ_CREATE processamento. Se tokenUser for especificado para o parâmetro TokenInformationClass passado para ZwQueryInformationToken, uma estrutura de TOKEN_USER será retornada no buffer apontado pelo parâmetro TokenInformation. Esse buffer retornado contém uma estrutura de SID_AND_ATTRIBUTES com o usuário SID.

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.

Nota

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

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