Funzione NtDuplicateToken (ntifs.h)
La funzione NtDuplicateToken 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
__kernel_entry NTSYSCALLAPI NTSTATUS NtDuplicateToken(
[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. NtDuplicateToken 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 Diritti di accesso per gli oggetti Access-Token. 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, viene restituito ntDuplicateToken restituisce STATUS_BAD_IMPERSONATION_LEVEL. |
| 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, ntDuplicateToken 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
ntDuplicateToken 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 se è stata specificata memoria in modalità utente non valida, NtDuplicateToken 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 | NtDuplicateToken non è stato possibile accedere a ExistingTokenHandle. Ciò si verifica se il token esistente non dispone del diritto di accesso TOKEN_DUPLICATE. |
| STATUS_INVALID_HANDLE | 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 macroInitializeObjectAttributesperché InitializeObjectAttributes attualmente imposta SecurityQualityOfService su NULL.
Per informazioni sull'analogico in modalità utente di NtDuplicateToken, vedere DuplicateTokenEx nella documentazione di Windows SDK.
Al termine dell'uso del nuovo token, chiamare la funzione NtClose per chiudere l'handle del token.
Se la chiamata alla funzione di NtDuplicateToken viene eseguita in modalità utente, è necessario usare il nome "NtDuplicateToken" anziché "NtDuplicateToken".
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, PowerIrpDDis |