Funzione ZwQueryInformationToken (ntifs.h)

Articolo
03/08/2023

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

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 TOKEN_INFORMATION_CLASS tipo enumerato 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 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 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 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 l'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 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 è vera, nel buffer TokenInformation non vengono restituiti dati:

La dimensione della struttura di 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 è TokenDefaultDacl e 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 ha avuto l'accesso necessario.
STATUS_BUFFER_TOO_SMALL	La dimensione della struttura di 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 sul token valida.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle non è un handle di token.

Commenti

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 SID_AND_ATTRIBUTES con il SID utente.

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 ZwQueryInformationToken si verifica in modalità utente, devi usare il nome "NtQueryInformationToken" anziché "ZwQueryInformationToken".

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows 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 .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

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