Funzione NtQueryInformationToken (ntifs.h)
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 |