Funzione ZwDuplicateToken (ntifs.h)

Articolo
04/30/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 a un token di accesso esistente aperto con il diritto di accesso TOKEN_DUPLICATE. Questo parametro è obbligatorio e non può essere NULL.

[in] DesiredAccess

Maschera 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 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
DELETE	Obbligatorio per eliminare l'oggetto.
READ_CONTROL	Obbligatorio per leggere le informazioni di daCL e proprietà per l'oggetto. Per l'accesso all'elenco di controllo di accesso del 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 modificare le informazioni sulla 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 READ_CONTROL.
STANDARD_RIGHTS_WRITE	Attualmente definito come uguale READ_CONTROL.
STANDARD_RIGHTS_EXECUTE	Attualmente definito come uguale READ_CONTROL.
STANDARD_RIGHTS_REQUIRED	Combina l'accesso a DELETE, READ_CONTROL, WRITE_DAC e WRITE_OWNER.
STANDARD_RIGHTS_ALL	Combina l'accesso DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER e SYNC. Tuttavia, il valore SYNC 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 l'elenco dati 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 collegare 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	Necessario 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 collegare 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 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 al token possibili per un token.

Per altre informazioni, vedere Diritti di accesso per gli oggetti Access-Token nel Windows SDK. Si noti che i token di accesso non supportano il diritto SYNC.

[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 membro SecurityDescriptor 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 parametro ObjectAttributes può essere usato per specificare il livello di rappresentazione del nuovo token. Questa operazione può essere eseguita impostando 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 è 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 nella parte effettiva (attualmente abilitata) del token. Se impostato su TRUE, verranno duplicati solo le parti attualmente abilitate del token di origine. Se impostato su FALSE, l'intero token esistente verrà duplicato. Ciò fornisce un mezzo per un chiamante di un sottosistema protetto per 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 potrebbe 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 dall'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 (come 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 al 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 è stata fornita, ZwDuplicateToken restituisce STATUS_ACCESS_VIOLATION.
STATUS_INSUFFICIENT_RESOURCES	Impossibile 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 a 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.

Commenti

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 ObjectAttributes facoltativo, il membro SecurityQualityOfService di OBJECT_ATTRIBUTES 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 aver chiamato la macro InitializeObjectAttributes perché InitializeObjectAttributes imposta attualmente 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 si verifica in modalità utente, è necessario usare il nome "NtDuplicateToken" anziché "ZwDuplicateToken".

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 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)

Vedi anche

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

SECURITY_IMPERSONATION_LEVEL

Condividi tramite