# 2.4. Token

This module expose the `Token` object that can be primarily retrieved through:

> - `windows.winobject.process.WinProcess.token`
> - `windows.winobject.process.WinThread.token`
> - `windows.current_process.token`
> - `windows.current_thread.token`
> - `windows.security.Token`

Note

If you need to directly access the `Token` class, please use `windows.security.Token` as the path of `token.py` may change.

Indeed `SecurityDescriptor` & `Token` are deeply related and I may move `token.py` to a `security/` directory in the futur.

Note

See sample Token

## 2.4.1. Token

class `windows.winobject.token.``Token`(handle)

  Represent a Windows Token. The attributes only documented by a type are from the `TOKEN_INFORMATION_CLASS`, such return values may be improved version of the structure.

  Note

  see [MSDN] TOKEN_INFORMATION_CLASS

  `TokenAccessInformation`

    `TOKEN_ACCESS_INFORMATION`

  `TokenAppContainerNumber`

    `DWORD`

  `TokenAppContainerSid`

    `TOKEN_APPCONTAINER_INFORMATION`

  `TokenCapabilities`

    `TokenGroups`

  `TokenDefaultDacl`

    `TOKEN_DEFAULT_DACL`

  `TokenDeviceClaimAttributes`

    `CLAIM_SECURITY_ATTRIBUTES_INFORMATION`

  `TokenDeviceGroups`

    `TokenGroups`

  `TokenElevation`

    `TOKEN_ELEVATION`

  `TokenElevationType`

    `TOKEN_ELEVATION_TYPE`

  `TokenGroups`

    `TokenGroups`

  `TokenGroupsAndPrivileges`

    `TOKEN_GROUPS_AND_PRIVILEGES`

  `TokenHasRestrictions`

    `DWORD`

  `TokenImpersonationLevel`

    `SECURITY_IMPERSONATION_LEVEL`

  `TokenIntegrityLevel`

    `TOKEN_MANDATORY_LABEL`

  `TokenIsAppContainer`

    `DWORD`

  `TokenLinkedToken`

    `TOKEN_LINKED_TOKEN`

  `TokenLogonSid`

    `TokenGroups`

  `TokenMandatoryPolicy`

    `TOKEN_MANDATORY_POLICY`

  `TokenOrigin`

    `TOKEN_ORIGIN`

  `TokenOwner`

    `TOKEN_OWNER`

  `TokenPrimaryGroup`

    `TOKEN_PRIMARY_GROUP`

  `TokenPrivileges`

    `TokenPrivileges`

  `TokenProcessTrustLevel`

    `PSID`

  `TokenRestrictedDeviceGroups`

    `TOKEN_GROUPS`

  `TokenRestrictedSids`

    `TokenGroups`

  `TokenSandBoxInert`

    `DWORD`

  `TokenSecurityAttributes`

    `TokenSecurityAttributesInformation`

  `TokenSessionId`

    `DWORD`

  `TokenSource`

    `TOKEN_SOURCE`

  `TokenStatistics`

    `TOKEN_STATISTICS`

  `TokenType`

    `TOKEN_TYPE`

  `TokenUIAccess`

    `DWORD`

  `TokenUser`

    `TOKEN_USER`

  `TokenUserClaimAttributes`

    `CLAIM_SECURITY_ATTRIBUTES_INFORMATION`

  `TokenVirtualizationAllowed`

    `DWORD`

  `TokenVirtualizationEnabled`

    `DWORD`

  `access_information`

    Alias for TokenAccessInformation (type may change in the future for improved struct)

  `adjust_privileges`(privileges)

    Adjust the token privileges according to `privileges`. This API is the complex one to adjust multiple privileges at once.

    To simply enable one privilege see `enable_privilege()`.

    Parameters: | privileges – `TOKEN_PRIVILEGES` (or subclass as `TokenPrivileges`). To easily update your token privileges use the result of `privileges`.

    Example:

        >>> tok = windows.current_process.token
        >>> privs = tok.privileges
        >>> privs["SeShutdownPrivilege"] = gdef.SE_PRIVILEGE_ENABLED
        >>> privs["SeUndockPrivilege"] = gdef.SE_PRIVILEGE_ENABLED
        >>> tok.adjust_privileges(privs)

  `appcontainer_number`

    Alias for TokenAppContainerNumber (type may change in the future for improved struct)

  `appcontainer_sid`

    The sid of the TokenAppContainerSid if present else `None`

    Type: | `PSID`

  `authentication_id`

    The AuthenticationId Specifies an unique identifier assigned to the session this token represents. There can be many tokens representing a single logon session.

    Type: | `int`

  `capabilities`

    Alias for TokenCapabilities (type may change in the future for improved struct)

  `computername`

    The computername of the token

    Type: | `str`

  `default_dacl`

    The defaul DACL of the token

    Type: | `windows.security.Acl`

  `duplicate`(access_rigth=MAXIMUM_ALLOWED(0x2000000), attributes=None, type=None, impersonation_level=None)

    Duplicate the token into a new `Token`.

    Parameters:

    - type – The type of token: `TokenPrimary(0x1L)` or `TokenImpersonation(0x2L)`
    - impersonation_level –

      The `SECURITY_IMPERSONATION_LEVEL` for a `TokenImpersonation(0x2L)`:

      - If `type` is `TokenPrimary(0x1L)` this parameter is ignored if `None` or used as-is.
      - If `type` is `TokenImpersonation(0x2L)` and this parameter is None, `self.impersonation_level` is used.
      - If `type` is `TokenImpersonation(0x2L)` and our Token is a `TokenPrimary(0x1L)` this parameter MUST be provided

    Returns: | `Token` - The duplicate token

    Example:

        >>> tok
        <Token TokenId=0x39d6dde5 Type=TokenPrimary(0x1L)>
        >>> tok.duplicate()
        <Token TokenId=0x39d7b206 Type=TokenPrimary(0x1L)>
        >>> tok.duplicate(type=gdef.TokenImpersonation)
        ...
        ValueError: Duplicating a PrimaryToken as a TokenImpersonation require explicit <impersonation_level> parameter
        >>> tok.duplicate(type=gdef.TokenImpersonation, impersonation_level=gdef.SecurityImpersonation)
        <Token TokenId=0x39dadbf8 Type=TokenImpersonation(0x2L) ImpersonationLevel=SecurityImpersonation(0x2L)>

  `elevated`

    `True` if token is an elevated token

  `elevation_type`

    The elevation type of the token.

    Type: | `int` – Enum value from `TOKEN_ELEVATION_TYPE`

  `enable_privilege`(name)

    Enable privilege `name` in the token

    Raises: | `ValueError` if `Token` has no privilege `name`

  `get_integrity`()

    Return the integrity level of the token

    Type: | `int`

  `groups`

    Alias for TokenGroups (type may change in the future for improved struct)

  `groups_and_privileges`

    Alias for TokenGroupsAndPrivileges (type may change in the future for improved struct)

  `handle`

    An handle on the object

    Type: | HANDLE Note The handle is automaticaly closed when the object is destroyed

  `has_restriction`

    Alias for TokenHasRestrictions (type may change in the future for improved struct)

  `id`

    The TokenId Specifies an unique identifier that identifies this instance of the token object.

    Type: | `int`

  `impersonation_level`

    The impersonation level of a `TokenImpersonation` token.

    Raises: | `WindowsError` if token is not a `TokenImpersonation`
    Type: | `int` – Enum value from `SECURITY_IMPERSONATION_LEVEL`

  `integrity`

    The integrity of the token as an int (extracted from integrity PSID)

    Getter: | `get_integrity()`
    Setter: | `set_integrity()`

  `integrity_level`

    The integrity level and attributes of the token

    Type: | `windows.generated_def.winstructs.SID_AND_ATTRIBUTES`

  `is_appcontainer`

    Alias for TokenIsAppContainer (type may change in the future for improved struct)

  `is_elevated`

    Alias for `elevated` deprecated and may disapear

  `linked_token`

    The token linked to our token if present (may raise else)

    Type: | `Token`

  `logon_sid`

    The logon sid of the token. (Case of multiple logon sid not handled and will raise AssertionError)

    Type: | `windows.generated_def.winstructs.SID_AND_ATTRIBUTES`

  `mandatory_policy`

    mandatory integrity access policy for the associated token

    Type: | `int` – see [MSDN] mandatory policy

  `modified_id`

    The ModifiedId Specifies an unique identifier that changes each time the token is modified.

    Type: | `int`

  `origin`

    The originating logon session of the token.

    Type: | `int`

  `owner`

    The owner sid of the token

    Type: | `PSID`

  `primary_group`

    The sid of the primary group of the token

    Type: | `PSID`

  `privileges`

    Alias for `TokenPrivileges`

    Type: | `TokenPrivileges`

  `restricted_sids`

    Alias for TokenRestrictedSids (type may change in the future for improved struct)

  `sandbox_inert`

    Alias for TokenSandBoxInert (type may change in the future for improved struct)

  `security_attributes`

    The security attributes of the token

    Type: | [`TokenSecurityAttributeV1`] - A list of token security attributes

  `session_id`

    Alias for TokenSessionId (type may change in the future for improved struct)

  `set_integrity`(integrity)

    Set the integrity level of a token

    Parameters: | type – `int`

  `statistics`

    Alias for TokenStatistics (type may change in the future for improved struct)

  `trust_level`

    The trust level of the process if present else `None`.

    Type: | `PSID`

  `type`

    The type (Primary / Impersonation) of the token

  `ui_access`

    Alias for TokenUIAccess (type may change in the future for improved struct)

  `user`

    The user sid of the token

    Type: | `PSID`

  `username`

    The username of the token

    Type: | `str`

  `virtualization_allowed`

    Alias for TokenVirtualizationAllowed (type may change in the future for improved struct)

  `virtualization_enabled`

    Alias for TokenVirtualizationEnabled (type may change in the future for improved struct)

  `wait`(timeout=INFINITE(0xffffffff))

    Wait for the object

## 2.4.2. TokenGroups

class `windows.winobject.token.``TokenGroups`

  Bases: `windows.generated_def.winstructs._TOKEN_GROUPS`

  `sids`

    The sids of each group

    Type: | [`PSID`] - A list of `PSID`

  `sids_and_attributes`

    The sids and attributes of each group

    Type: | [`SID_AND_ATTRIBUTES`] - A list of `SID_AND_ATTRIBUTES`

## 2.4.3. TokenPrivileges

class `windows.winobject.token.``TokenPrivileges`

  Bases: `windows.generated_def.winstructs._TOKEN_PRIVILEGES`

  Improved `TOKEN_PRIVILEGES` usable like a mapping

  `__getitem__`(name)

    Retrieve the attribute value for privilege `name`

    Raises: | KeyError if privilege `name` not in the TokenPrivileges
    Returns: | `int`

  `__setitem__`(name, value)

    Set the attribute value for privilege `name`

    Raises: | KeyError if privilege `name` not in the TokenPrivileges

  `all`()

    The list of all privileges

    Returns: | [`LUID_AND_ATTRIBUTES`] - A list of `LUID_AND_ATTRIBUTES`

  `items`()

    The (name, Attribute) of all privileges in the TokenPrivileges

    Returns: | [(`str`, `int`)] - A list of (name, Attribute) tuple

  `keys`()

    The name of all privileges in the TokenPrivileges

    Returns: | [`str`] - A list of name

## 2.4.4. TokenSecurityAttributesInformation

class `windows.winobject.token.``TokenSecurityAttributesInformation`

  Bases: `windows.generated_def.winstructs._TOKEN_SECURITY_ATTRIBUTES_INFORMATION`

  `attributes`

    Return all the attributes as `TokenSecurityAttributeV1`

    Type: | [`TokenSecurityAttributeV1`] - A list of token security attributes

## 2.4.5. TokenSecurityAttributeV1

class `windows.winobject.token.``TokenSecurityAttributeV1`

  Bases: `windows.generated_def.winstructs._TOKEN_SECURITY_ATTRIBUTE_V1`

  `name`

    The name of the security attribute

  `values`

    The values of the security attribute