DuplicateTokenEx
[New
- Windows NT]
The DuplicateTokenEx
function creates a new access token that duplicates an existing token. This
function can create either a primary token or an impersonation token.
BOOL DuplicateTokenEx(
|
HANDLE hExistingToken, |
// handle to token
to duplicate |
|
DWORD dwDesiredAccess, |
// access rights of
new token |
|
LPSECURITY_ATTRIBUTES lpTokenAttributes, |
// security
attributes of the new token |
|
SECURITY_IMPERSONATION_LEVEL ImpersonationLevel, |
// impersonation
level of new token |
|
TOKEN_TYPE TokenType, |
// primary or
impersonation token |
|
PHANDLE phNewToken |
// handle to
duplicated token |
|
); |
|
Parameters
hExistingToken
Identifies an
access token opened with TOKEN_DUPLICATE access.
dwDesiredAccess
Specifies the
requested access rights for the new token. The DuplicateTokenEx function
compares the requested access rights with the existing token s discretionary
access-control list (ACL) to determine which rights are granted or denied. To
request the same access rights as the existing token, specify zero. To request
all access rights that are valid for the caller, specify MAXIMUM_ALLOWED.
Otherwise, specify a combination of the following access rights.
|
Value |
Meaning |
|
TOKEN_ADJUST_DEFAULT |
Required to
change the default ACL, primary group, or owner of an access token. |
|
TOKEN_ADJUST_GROUPS |
Required to
change the groups specified in an access token. |
|
TOKEN_ADJUST_PRIVILEGES |
Required to
change the privileges specified in an access token. |
|
TOKEN_ALL_ACCESS |
Combines
the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access
rights for tokens. |
|
TOKEN_ASSIGN_PRIMARY |
Required to
attach a primary token to a process in addition to the SE_CREATE_TOKEN_NAME
privilege. |
|
TOKEN_DUPLICATE |
Required to
duplicate an access token. |
|
TOKEN_EXECUTE |
Combines
the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access
right. |
|
TOKEN_IMPERSONATE |
Required to
attach an impersonation access token to a process. |
|
TOKEN_QUERY |
Required to
query the contents of an access token. |
|
TOKEN_QUERY_SOURCE |
Required to
query the source of an access token. |
|
TOKEN_READ |
Combines
the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access
right. |
|
TOKEN_WRITE |
Combines
the STANDARD_RIGHTS_WRITE standard access rights and the
TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access
rights. |
lpTokenAttributes
Pointer to a SECURITY_ATTRIBUTES structure that specifies a
security descriptor for the new token and determines whether child processes
can inherit the token. If lpTokenAttributes is NULL, the token gets a
default security descriptor and the handle cannot be inherited.
ImpersonationLevel
Specifies a
value from the SECURITY_IMPERSONATION_LEVEL enumeration that indicates the impersonation
level of the new token.
TokenType
Specifies one
of the following values from the TOKEN_TYPE enumeration.
|
Value |
Meaning |
|
TokenPrimary |
The new
token is a primary token that you can use in the CreateProcessAsUser function. |
|
TokenImpersonation |
The new
token is an impersonation token. |
phNewToken
Pointer to a HANDLE
variable that receives the new token.
Return Values
If the
function succeeds, the return value is a nonzero value.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
The DuplicateTokenEx
function allows you to create a primary token that you can use in the CreateProcessAsUser function. This allows a
server application that is impersonating a client to create a process that has
the security context of the client. Note that the DuplicateToken
function can create only impersonation tokens, which are not valid for CreateProcessAsUser.
The following
is a typical scenario for using DuplicateTokenEx to create a primary
token. A server application creates a thread that calls one of the impersonation
functions, such as ImpersonateNamedPipeClient179WHKW, to impersonate a client. The
impersonating thread then calls the OpenThreadToken function to get its own
token, which is an impersonation token that has the security context of
the client. The thread specifies this impersonation token in a call to DuplicateTokenEx,
specifying the TokenPrimary flag. DuplicateTokenEx creates a primary
token that has the security context of the client.
When you have
finished using the new token, call the CloseHandle function to close the
token handle.
See Also