Funzione NtQueryInformationToken (ntifs.h)

Articolo
02/26/2024

La routine NtQueryInformationToken recupera un tipo specificato di informazioni su un token di accesso. Il processo di chiamata deve avere diritti di accesso appropriati per ottenere le informazioni.

Sintassi

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Parametri

[in] TokenHandle

Gestire per un token di accesso da cui recuperare le informazioni. Se TokenInformationClass è impostato su TokenSource, l'handle deve avere accesso TOKEN_QUERY_SOURCE. Per tutti gli altri valori TokenInformationClass , l'handle deve avere accesso TOKEN_QUERY. Per altre informazioni sui diritti di accesso per gli oggetti token di accesso, vedere la sezione Sicurezza della documentazione di Windows SDK.

[in] TokenInformationClass

Valore del tipo enumerato TOKEN_INFORMATION_CLASS che identifica il tipo di informazioni da recuperare. I valori possibili per questo parametro sono elencati nella colonna TokenInformationClass Value della tabella illustrata nella descrizione del parametro TokenInformation .

[out] TokenInformation

Puntatore a un buffer allocato dal chiamante che riceve le informazioni richieste sul token. La struttura inserita in questo buffer dipende dal valore di TokenInformationClass, come illustrato nella tabella seguente. Tutte le strutture devono essere allineate su un limite a 32 bit.

Valore TokenInformationClass	Effetto sul buffer TokenInformation
TokenDefaultDacl	Il buffer riceve una struttura TOKEN_DEFAULT_DACL contenente l'elenco dati predefinito per gli oggetti appena creati.
TokenGroup	Il buffer riceve una struttura TOKEN_GROUPS contenente gli account di gruppo associati al token.
TokenImpersonationLevel	Il buffer riceve un valore SECURITY_IMPERSONATION_LEVEL che indica il livello di rappresentazione del token. Se il token di accesso non è un token di rappresentazione, la chiamata a NtQueryInformationToken ha esito negativo.
TokenOwner	Il buffer riceve una struttura TOKEN_OWNER contenente il SID del proprietario predefinito per gli oggetti appena creati.
TokenPrimaryGroup	Il buffer riceve una struttura TOKEN_PRIMARY_GROUP contenente il SID del gruppo primario predefinito per gli oggetti appena creati.
TokenPrivileges	Il buffer riceve una struttura TOKEN_PRIVILEGES contenente i privilegi del token.
TokenSessionId	Il buffer riceve un valore a 32 bit che specifica l'identificatore di sessione di Servizi terminal associato al token. Se il token è associato alla sessione della console di Terminal Server, l'identificatore della sessione è zero. Un identificatore di sessione diverso da zero indica una sessione client di Servizi terminal. In un ambiente non Terminal Services l'identificatore di sessione è zero.
TokenSource	Il buffer riceve una struttura TOKEN_SOURCE contenente l'origine del token. TOKEN_QUERY_SOURCE l'accesso è necessario per recuperare queste informazioni.
TokenStatistici	Il buffer riceve una struttura TOKEN_STATISTICS contenente varie statistiche del token.
TokenType	Il buffer riceve un valore TOKEN_TYPE che indica se il token è un token primario o di rappresentazione.
TokenUser	Il buffer riceve una struttura TOKEN_USER contenente l'account utente del token.

[in] TokenInformationLength

Lunghezza, in byte, del buffer TokenInformation allocato dal chiamante.

[out] ReturnLength

Puntatore a una variabile allocata dal chiamante che riceve la lunghezza effettiva, in byte, delle informazioni restituite nel buffer TokenInformation . Se una delle condizioni seguenti è true, nessun dato viene restituito nel buffer TokenInformation :

La dimensione della struttura delle informazioni sul token richiesto è maggiore di TokenInformationLength. In questo caso , ReturnLength riceve il numero effettivo di byte necessari per archiviare le informazioni richieste.
Il valore di TokenInformationClass è TokenDefaultDacl e non è stato stabilito un daCL predefinito per il token. In questo caso , ReturnLength riceve zero.

ReturnLength non può essere NULL. Per altre informazioni, vedere Osservazioni.

Valore restituito

NtQueryInformationToken restituisce STATUS_SUCCESS o uno stato di errore appropriato. I codici di stato degli errori possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_ACCESS_DENIED	TokenHandle non ha avuto l'accesso richiesto.
STATUS_BUFFER_TOO_SMALL	La dimensione della struttura delle informazioni sul token richiesto è maggiore di TokenInformationLength. Il numero di byte necessari viene restituito in ReturnLength.
STATUS_ACCESS_VIOLATION	ReturnLength era NULL o non era scrivibile per ricevere la lunghezza effettiva delle informazioni indicate da TokenInformation.
STATUS_INVALID_HANDLE	TokenHandle non era un handle valido.
STATUS_INVALID_INFO_CLASS	TokenInformationClass non era una classe di informazioni sul token valida.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle non era un handle token.

Commenti

La routine NtQueryInformationToken può essere usata da un driver di filtro file system o file system per determinare il SID del chiamante che ha avviato la richiesta durante l'elaborazione IRP_MJ_CREATE. Se TokenUser viene specificato per il parametro TokenInformationClass passato a NtQueryInformationToken, viene restituita una struttura TOKEN_USER nel buffer a cui fa riferimento il parametro TokenInformation . Questo buffer restituito contiene una struttura SID_AND_ATTRIBUTES con il SID utente.

A causa della natura delle proprietà del token (ad esempio l'utente del token, il gruppo primario token, i privilegi e così via, dove il loro contenuto può variare in ogni token), ReturnLength non è facoltativo; ovvero, non può essere NULL. Questo perché SID è una struttura a lunghezza variabile mentre un privilegio specifico può esistere in un token ma non in un altro (il conteggio dei privilegi può essere diverso per ogni token). È responsabilità del chiamante eseguire prima una query sulle dimensioni di lunghezza necessarie per allocare la memoria per soddisfare le informazioni sul token richiesto prima di eseguire la query effettiva. Detto questo, è anche responsabilità del chiamante fornire una variabile ReturnLength valida che è scrivibile e non NULL. In uno scenario NULL, la funzione genera un'eccezione di violazione di accesso.

Per altre informazioni sul controllo di sicurezza e accesso, vedere Modello di sicurezza di Windows per sviluppatori driver e la documentazione su questi argomenti in Windows SDK.

Nota

Se la chiamata alla funzione NtQueryInformationToken si verifica in modalità utente, è necessario usare il nome "NtQueryInformationToken" anziché "ZwQueryInformationToken".

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis