Funzione ZwOpenThreadTokenEx (ntifs.h)

Articolo
12/22/2024

La routine zwOpenThreadTokenEx apre il token di accesso associato a un thread.

Sintassi

NTSYSAPI NTSTATUS ZwOpenThreadTokenEx(
  [in]  HANDLE      ThreadHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  BOOLEAN     OpenAsSelf,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);

Parametri

[in] ThreadHandle

Handle per il thread il cui token di accesso deve essere aperto. L'handle deve avere accesso THREAD_QUERY_INFORMATION. Utilizzare la macro ntCurrentThread per specificare il thread corrente.

[in] DesiredAccess

ACCESS_MASK struttura che specifica i tipi richiesti di accesso al token di accesso. Questi tipi di accesso richiesti vengono confrontati con l'elenco di controllo di accesso discrezionale del token (DACL) per determinare quali diritti di accesso vengono concessi o negati.

[in] OpenAsSelf

Valore booleano che specifica se il controllo di accesso deve essere eseguito sul contesto di sicurezza del thread che chiama ZwOpenThreadTokenEx o sul contesto di sicurezza del processo per il thread chiamante.

Se questo parametro è FALSE, il controllo di accesso viene eseguito usando il contesto di sicurezza per il thread chiamante. Se il thread rappresenta un client, questo contesto di sicurezza può essere quello di un processo client. Se questo parametro è TRUE, il controllo di accesso viene eseguito usando il contesto di sicurezza del processo per il thread chiamante.

[in] HandleAttributes

Attributi per l'handle creato. Attualmente è supportato solo OBJ_KERNEL_HANDLE. Se il chiamante non è in esecuzione nel contesto del processo di sistema, deve specificare OBJ_KERNEL_HANDLE per questo parametro.

[out] TokenHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle per il token di accesso appena aperto.

Valore restituito

ZwOpenThreadTokenEx 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	ThreadHandle non ha avuto accesso THREAD_QUERY_INFORMATION.
STATUS_CANT_OPEN_ANONYMOUS	Il client ha richiesto il livello di rappresentazione SecurityAnonymous. Tuttavia, non è possibile aprire un token anonimo. Per altre informazioni, vedere SECURITY_IMPERSONATION_LEVEL.
STATUS_INVALID_HANDLE	threadHandle non è un handle valido.
STATUS_INVALID_PARAMETER	Il HandleAttributes specificato non include OBJ_KERNEL_HANDLE.
STATUS_NO_TOKEN	È stato effettuato un tentativo di aprire un token associato a un thread che attualmente non rappresenta un client.
STATUS_OBJECT_TYPE_MISMATCH	threadHandle non era un handle di thread.

Osservazioni

ZwOpenThreadTokenEx apre il token di accesso associato a un thread e restituisce un handle per tale token.

Il parametro openAsSelf consente a un processo server di aprire il token di accesso per un processo client quando il processo client ha specificato il livello di rappresentazione SecurityIdentification per il tipo enumerato SECURITY_IMPERSONATION_LEVEL. Senza questo parametro, il processo chiamante non è in grado di aprire il token di accesso del client usando il contesto di sicurezza del client perché non è possibile aprire oggetti a livello esecutivo usando il livello di rappresentazione SecurityIdentification.

Qualsiasi handle ottenuto chiamando ZwOpenThreadTokenEx deve essere rilasciato chiamando ZwClose.

Le routine del driver eseguite in un contesto di processo diverso da quello del processo di sistema devono impostare l'attributo OBJ_KERNEL_HANDLE per il parametro handleAttributes parametro di ZwOpenThreadTokenEx. Ciò limita l'uso dell'handle restituito da ZwOpenThreadTokenEx ai processi in esecuzione in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver.

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 ZwOpenThreadTokenEx si verifica in modalità utente, è necessario usare il nome "NtOpenThreadTokenEx" anziché "ZwOpenThreadTokenEx".

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)