Funzione ZwDuplicateToken (ntifs.h)
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) |