Funzione DuplicateTokenEx (securitybaseapi.h)
La funzione DuplicateTokenEx crea un nuovo token di accesso che duplica un token esistente. Questa funzione può creare un token primario o un token di rappresentazione.
Sintassi
BOOL DuplicateTokenEx(
[in] HANDLE hExistingToken,
[in] DWORD dwDesiredAccess,
[in, optional] LPSECURITY_ATTRIBUTES lpTokenAttributes,
[in] SECURITY_IMPERSONATION_LEVEL ImpersonationLevel,
[in] TOKEN_TYPE TokenType,
[out] PHANDLE phNewToken
);
Parametri
[in] hExistingToken
Handle a un token di accesso aperto con l'accesso TOKEN_DUPLICATE.
[in] dwDesiredAccess
Specifica i diritti di accesso richiesti per il nuovo token. La funzione DuplicateTokenEx 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. 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.
Per un elenco dei diritti di accesso per i token di accesso, vedere Diritti di accesso per gli oggetti Access-Token.
[in, optional] lpTokenAttributes
Puntatore a una struttura di SECURITY_ATTRIBUTES che specifica un descrittore di sicurezza per il nuovo token e determina se i processi figlio possono ereditare il token. Se lpTokenAttributes è NULL, il token ottiene un descrittore di sicurezza predefinito e l'handle non può essere ereditato. Se il descrittore di sicurezza contiene un elenco di controllo di accesso del sistema (SACL), il token ottiene ACCESS_SYSTEM_SECURITY diritto di accesso, anche se non è stato richiesto in dwDesiredAccess.
Per impostare il proprietario nel descrittore di sicurezza per il nuovo token, il token di processo del chiamante deve avere il privilegio SE_RESTORE_NAME impostato.
[in] ImpersonationLevel
Specifica un valore dell'enumerazione SECURITY_IMPERSONATION_LEVEL che indica il livello di rappresentazione del nuovo token.
[in] TokenType
Specifica uno dei valori seguenti dall'enumerazione TOKEN_TYPE .
| Valore | Significato |
|---|---|
|
Il nuovo token è un token primario che è possibile usare nella funzione CreateProcessAsUser . |
|
Il nuovo token è un token di rappresentazione. |
[out] phNewToken
Puntatore a una variabile HANDLE che riceve il nuovo token.
Al termine dell'uso del nuovo token, chiamare la funzione CloseHandle per chiudere l'handle del token.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.
Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
La funzione DuplicateTokenEx consente di creare un token primario che è possibile usare nella funzione CreateProcessAsUser . Ciò consente a un'applicazione server che rappresenta un client di creare un processo con il contesto di sicurezza del client. Si noti che la funzione DuplicateToken può creare solo token di rappresentazione, che non sono validi per CreateProcessAsUser.
Di seguito è riportato uno scenario tipico per l'uso di DuplicateTokenEx per creare un token primario. Un'applicazione server crea un thread che chiama una delle funzioni di rappresentazione, ad esempio ImpersonateNamedPipeClient, per rappresentare un client. Il thread di rappresentazione chiama quindi la funzione OpenThreadToken per ottenere il proprio token, ovvero un token di rappresentazione con il contesto di sicurezza del client. Il thread specifica questo token di rappresentazione in una chiamata a DuplicateTokenEx, specificando il flag TokenPrimary. La funzione DuplicateTokenEx crea un token primario con il contesto di sicurezza del client.
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | securitybaseapi.h (include Windows.h) |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |