Funzione ZwDuplicateToken (ntifs.h)

Articolo
12/21/2024

La funzione ZwDuplicateToken crea un handle per un nuovo token di accesso che duplica un token esistente. Questa funzione può creare un token primario o un token di rappresentazione.

Sintassi

NTSYSAPI NTSTATUS ZwDuplicateToken(
  [in]  HANDLE             ExistingTokenHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            EffectiveOnly,
  [in]  TOKEN_TYPE         TokenType,
  [out] PHANDLE            NewTokenHandle
);

Parametri

[in] ExistingTokenHandle

Handle per un token di accesso esistente aperto con il diritto di accesso TOKEN_DUPLICATE. Questo parametro è obbligatorio e non può essere NULL.

[in] DesiredAccess

Maschera di bit che specifica i diritti di accesso richiesti per il nuovo token. ZwDuplicateToken confronta i diritti di accesso richiesti con l'elenco di controllo di accesso discrezionale (DACL) del token esistente per determinare quali diritti vengono concessi o negati al nuovo token. Per richiedere gli stessi diritti di accesso del token esistente, specificare zero. Per richiedere tutti i diritti di accesso validi per il chiamante, specificare MAXIMUM_ALLOWED. Questo parametro è facoltativo e può essere zero, MAXIMUM_ALLOWED o una combinazione OR bit per bit di uno o più dei valori seguenti:

Valore	Significato
CANCELLARE	Obbligatorio per eliminare l'oggetto.
READ_CONTROL	Obbligatorio per leggere le informazioni su DACL e proprietà per l'oggetto. Per l'accesso all'elenco di controllo di accesso di sistema (SACL), vedere ACCESS_SYSTEM_SECURITY più avanti in questa tabella.
WRITE_DAC	Obbligatorio per modificare le informazioni DACL per l'oggetto .
WRITE_OWNER	Obbligatorio per modificare le informazioni di proprietà nel descrittore di sicurezza dell'oggetto (SECURITY_DESCRIPTOR).
ACCESS_SYSTEM_SECURITY	Obbligatorio per ottenere o impostare sacl nell'ACL di un oggetto. Il sistema operativo concede questo diritto al nuovo token solo se il privilegio SE_SECURITY_NAME è abilitato nel token di accesso del thread chiamante.
STANDARD_RIGHTS_READ	Attualmente definito come uguale a READ_CONTROL.
STANDARD_RIGHTS_WRITE	Attualmente definito come uguale a READ_CONTROL.
STANDARD_RIGHTS_EXECUTE	Attualmente definito come uguale a READ_CONTROL.
STANDARD_RIGHTS_REQUIRED	Combina l'accesso DELETE, READ_CONTROL, WRITE_DAC e WRITE_OWNER.
STANDARD_RIGHTS_ALL	Combina l'accesso DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER e SYNCHRONIZE. Tuttavia, il valore SYNCHRONIZE non è applicabile agli oggetti token. Pertanto, STANDARD_RIGHTS_ALL ha un equivalente funzionale a STANDARD_RIGHTS_REQUIRED.
TOKEN_ADJUST_DEFAULT	Obbligatorio per modificare il proprietario predefinito, il gruppo primario o DACL di un token di accesso.
TOKEN_ADJUST_GROUPS	Necessario per modificare gli attributi dei gruppi in un token di accesso.
TOKEN_ADJUST_PRIVILEGES	Obbligatorio per abilitare o disabilitare i privilegi in un token di accesso.
TOKEN_ADJUST_SESSIONID	Obbligatorio per modificare l'ID sessione (SID) di un token di accesso. Il sistema operativo concede questo diritto al nuovo token solo se il privilegio SE_TCB_NAME è abilitato nel token di accesso del thread chiamante.
TOKEN_ASSIGN_PRIMARY	Obbligatorio per associare un token primario a un processo. Il sistema operativo concede questo diritto al nuovo token solo se il privilegio SE_ASSIGNPRIMARYTOKEN_NAME è abilitato nel token di accesso del thread chiamante.
TOKEN_DUPLICATE	Obbligatorio per duplicare un token di accesso. Si noti che il token ExistingTokenHandle specificato deve contenere questo diritto per poter usare correttamente questa routine.
TOKEN_EXECUTE	Combina STANDARD_RIGHTS_EXECUTE e TOKEN_IMPERSONATE.
TOKEN_IMPERSONATE	Obbligatorio per associare un token di accesso di rappresentazione a un processo.
TOKEN_QUERY	Obbligatorio per eseguire query su un token di accesso.
TOKEN_QUERY_SOURCE	Obbligatorio per eseguire una query sull'origine di un token di accesso.
TOKEN_READ	Combina STANDARD_RIGHTS_READ e TOKEN_QUERY.
TOKEN_WRITE	Combina STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS e TOKEN_ADJUST_DEFAULT.
TOKEN_ALL_ACCESS	Combina tutte le autorizzazioni di accesso ai token possibili per un token.

Per altre informazioni, vedere Access Rights for Access-Token Objects in Windows SDK. Si noti che i token di accesso non supportano il diritto SYNCHRONIZE.

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che descrive le proprietà richieste per il nuovo token. Il parametro ObjectAttributes è facoltativo e può essere NULL. Se il parametro ObjectAttributes è NULL o se il SecurityDescriptor membro della struttura a cui punta il parametro ObjectAttributes è NULL, il nuovo token riceve un descrittore di sicurezza predefinito e il nuovo handle di token non può essere ereditato. In tal caso, questo descrittore di sicurezza predefinito viene creato dal gruppo di utenti, dal gruppo primario e dalle informazioni DACL archiviate nel token del chiamante.

Quando il parametro TokenType è impostato su TokenImpersonation:

Il ObjectAttributes parametro può essere usato per specificare il livello di rappresentazione del nuovo token. A tale scopo, è possibile impostare ObjectAttributes->SecurityQualityOfService.ImpersonationLevel su un valore di enumerazione SECURITY_IMPERSONATION_LEVEL appropriato. Per altre informazioni, vedere SECURITY_QUALITY_OF_SERVICE.
Se il token esistente è un token di rappresentazione e il parametro ObjectAttributes non fornisce informazioni di rappresentazione, il livello di rappresentazione del nuovo token viene impostato sul livello di rappresentazione del token esistente.
Se il token esistente è un token primario e non vengono fornite informazioni sul livello di rappresentazione, il nuovo token di rappresentazione avrà un livello di rappresentazione SECURITY_IMPERSONATION_LEVEL.

[in] EffectiveOnly

Valore booleano che indica se l'intero token esistente deve essere duplicato nel nuovo token o solo la parte effettiva (attualmente abilitata) del token. Se impostato su TRUE, verranno duplicate solo le parti attualmente abilitate del token di origine. Se impostato su FALSE, l'intero token esistente verrà duplicato. Ciò consente a un chiamante di un sottosistema protetto di limitare i gruppi e i privilegi facoltativi resi disponibili per il sottosistema protetto. Ad esempio, se EffectiveOnly è TRUE, il chiamante potrebbe duplicare un token ma rimuovere il gruppo Administrators e il diritto SeTcbPrivilege. Il token risultante può quindi essere passato a un processo figlio (CreateProcessAsUser), che limita le operazioni che il processo figlio può eseguire. Questo parametro è obbligatorio.

[in] TokenType

Specifica uno dei valori seguenti dell'enumerazione TOKEN_TYPE.

Valore	Significato
TokenPrimary	Il nuovo token è un token primario. Se il token esistente è un token di rappresentazione, il token di rappresentazione esistente deve avere un livello di rappresentazione (fornito dal parametro ObjectAttributes) di SecurityImpersonation o SecurityDelegation. In caso contrario, ZwDuplicateToken restituisce STATUS_BAD_IMPERSONATION_LEVEL viene restituito.
TokenImpersonation	Il nuovo token è un token di rappresentazione. Se il token esistente è un token di rappresentazione, il livello di rappresentazione richiesto (come fornito dal parametro ObjectAttributes) del nuovo token non deve essere maggiore del livello di rappresentazione del token esistente. In caso contrario, ZwDuplicateToken restituisce STATUS_BAD_IMPERSONATION_LEVEL.

Il parametro TokenType è obbligatorio e non può essere NULL.

[out] NewTokenHandle

Puntatore a una variabile allocata dal chiamante, di tipo HANDLE, che riceve un handle per il nuovo token. Questo parametro è obbligatorio e non può essere NULL.

Valore restituito

ZwDuplicateToken restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I codici restituiti di errore possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_ACCESS_VIOLATION	Si è verificata una violazione dell'accesso alla memoria. Ad esempio, se la modalità precedente era in modalità utente e la memoria in modalità utente non è valida, ZwDuplicateToken restituisce STATUS_ACCESS_VIOLATION.
STATUS_INSUFFICIENT_RESOURCES	Non è stato possibile allocare memoria sufficiente per duplicare il nuovo token.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_BAD_IMPERSONATION_LEVEL	Il livello di rappresentazione richiesto per il nuovo token è maggiore del livello di rappresentazione del token esistente.
STATUS_ACCESS_DENIED	ZwDuplicateToken restituisce STATUS_ACCESS_DENIED se non è stato possibile accedere ExistingTokenHandle. Ciò si verifica se il token esistente non dispone del diritto di accesso TOKEN_DUPLICATE.
STATUS_INVALID_HANDLE	ZwDuplicateToken restituisce STATUS_INVALID_HANDLE se ExistingTokenHandle fa riferimento a un handle non valido.

Osservazioni

Se non sono state fornite informazioni sul livello di rappresentazione dal parametro ObjectAttributes, verrà usato il livello di rappresentazione del token esistente per il nuovo token.

Per quanto riguarda la struttura a cui punta il parametro facoltativo ObjectAttributes, il OBJECT_ATTRIBUTES membro securityQualityOfService punta a una struttura di tipo SECURITY_QUALITY_OF_SERVICE. Per informazioni sui membri di questa struttura, vedere SECURITY_QUALITY_OF_SERVICE.

Il membro SecurityQualityOfService deve essere impostato dopo chiamare la macro InitializeObjectAttributes perché InitializeObjectAttributes attualmente imposta SecurityQualityOfService su NULL.

Per informazioni sull'analogico in modalità utente di ZwDuplicateToken, vedere DuplicateTokenEx.

Al termine dell'uso del nuovo token, chiamare la funzione ZwClose per chiudere l'handle del token.

Se la chiamata alla funzione ZwDuplicateToken viene eseguita in modalità utente, è necessario usare il nome "NtDuplicateToken" invece di "ZwDuplicateToken".

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 2000
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h, FltKernel.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Vedere anche

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL

Condividi tramite