Funzione DuplicateTokenEx (securitybaseapi.h)

Articolo
08/25/2023

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
TokenPrimary	Il nuovo token è un token primario che è possibile usare nella funzione CreateProcessAsUser .
TokenImpersonation	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