Funzione ZwQueryInformationToken (ntifs.h)

Articolo
12/21/2024

La routine ZwQueryInformationToken recupera un tipo specificato di informazioni su un token di accesso. Il processo chiamante deve disporre dei diritti di accesso appropriati per ottenere le informazioni.

Sintassi

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

Parametri

[in] TokenHandle

Handle 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 Valore 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 il DACL predefinito per gli oggetti appena creati.
TokenGroups	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 ZwQueryInformationToken ha esito negativo.
TokenOwner	Il buffer riceve una struttura di TOKEN_OWNER contenente il proprietario predefinito SID 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 di 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'accesso è necessario per recuperare queste informazioni.
tokenStatistics	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 Token Information 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 è vera, non vengono restituiti dati nel buffer TokenInformation :

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

Valore restituito

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

Codice restituito	Descrizione
STATUS_ACCESS_DENIED	tokenHandle non dispone dell'accesso necessario.
STATUS_BUFFER_TOO_SMALL	La dimensione della struttura delle informazioni sul token richiesta è maggiore di TokenInformationLength. Il numero di byte necessari viene restituito in ReturnLength.
STATUS_INVALID_HANDLE	TokenHandle non è un handle valido.
STATUS_INVALID_INFO_CLASS	tokenInformationClass non era una classe di informazioni token valida.
STATUS_OBJECT_TYPE_MISMATCH	tokenHandle non era un handle di token.

Osservazioni

La routine ZwQueryInformationToken può essere utilizzata da un driver di filtro del file system o del 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 ZwQueryInformationToken, viene restituita una struttura TOKEN_USER nel buffer a cui punta il parametro TokenInformation . Questo buffer restituito contiene una struttura di SID_AND_ATTRIBUTES con l'utente SID.

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

Nota

Se la chiamata alla funzione di ZwQueryInformationToken viene eseguita in modalità utente, devi usare il nome "NtQueryInformationToken" invece di "ZwQueryInformationToken".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni 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 Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

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(storport), PowerIrpDDis(wdm)