# 5. `windows.security` – Security Descriptor & related

This module give access to `SecurityDescriptor` and related structures (`Acl` & `Ace`).

Note

See sample windows.security

## 5.1. Token

The `windows.security` module is the official module where to retrieve the `Token` class if ever needed.

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

    >>> windows.security.Token
    <class 'windows.winobject.token.Token'>

## 5.2. SecurityDescriptor

class `windows.security.``SecurityDescriptor`

  A Security Descriptor

  Warning

  TODO: free the underliying buffer when not needed anymore for now the underliying memory is never freed.

  `SERVICE_SECURITY_INFORMATION` = 7L

    The default `flags` value for functions expecting a SECURITY_INFORMATION.

    This value regroups the followings flags:

    > - `OWNER_SECURITY_INFORMATION`
    > - `GROUP_SECURITY_INFORMATION`
    > - `DACL_SECURITY_INFORMATION`
    > - `ATTRIBUTE_SECURITY_INFORMATION`
    > - `SCOPE_SECURITY_INFORMATION`
    > - `PROCESS_TRUST_LABEL_SECURITY_INFORMATION`
    > - `LABEL_SECURITY_INFORMATION`

    Warning

    Note that the value `SACL_SECURITY_INFORMATION` needed to access the SACL is not present as it require the `SeSecurityPrivilege`.

    To query the SACL enable the `SeSecurityPrivilege` and use the parameter `query_sacl=True` on the functions expecting a `flags`

    see Query SACL sample

  `control`

    The security descriptor control

    Type: | `SECURITY_DESCRIPTOR_CONTROL`

  `dacl`

    The DACL of the security descriptor.

    Type: | `Acl` or `None` if the DACL was `NULL` or not present

  classmethod `from_binary`(data)

    Retrieve the security descriptor described by the binary `data`. Binary security descriptor can be found in the registry for example

  classmethod `from_filename`(filename, query_sacl=False, flags=247L)

    Retrieve the security descriptor for the file `filename`

  classmethod `from_handle`(handle, query_sacl=False, flags=247L, obj_type=None)

    Retrieve the security descriptor for the kernel object described by``handle``

  classmethod `from_service`(filename, query_sacl=False, flags=7L)

    Retrieve the security descriptor for the service named `service`

  classmethod `from_string`(sddl)

    Return a new `SecurityDescriptor` from the `SDDL`.

    Returns: | `SecurityDescriptor`

    Warning

    At the moment the underliying buffer is never freed.

    See ConvertStringSecurityDescriptorToSecurityDescriptorA

  `group`

    The group of the security descriptor

    Type: | `PSID` or `None`

  `owner`

    The owner of the security descriptor

    Type: | `PSID` or `None`

  `revision`

    The security descriptor’s revision

    Type: | `int`

  `sacl`

    The SACL of the security descriptor. You may need special attention to retrieve it (see `DEFAULT_SECURITY_INFORMATION`)

    Type: | `Acl` or `None` if the SACL was `NULL` or not present

  `to_filename`(filename, flags=0)

    Test method: WILL CHANGE

  `to_string`(security_information=247L)

    Return the SDDL representation of the security descriptor

    Type: | `str`

  `value`

    current value

## 5.3. Acl

class `windows.security.``Acl`

  All the `ACE` returned by `Acl` methods/property are described in the Ace section

  `__getitem__`(i)

    Return `ACE` nb `i`

    Returns: | `Ace`

  `__iter__`()

    Return an iterable over all the `ACE` in the `Acl`

    Yield: | `Ace`

  `__len__`()

    The number of `ACE` in the `Acl`

  `aces`

    The list of `ACE` in the ACL `Acl`

    Type: | [`Ace`] - A list of ACE

  `get_ace`(i)

    Retrieve `ACE` number `i`

    Returns: | `Ace`

## 5.4. Ace

The ACE are regrouped in two categories.

The DACL related ACEs:

> - `AccessAllowedACE`
> - `AccessDeniedACE`
> - `AccessAllowedCallbackACE`
> - `AccessDeniedCallbackACE`
> - `AccessAllowedObjectACE`
> - `AccessDeniedObjectACE`
> - `AccessAllowedCallbackObjectACE`
> - `AccessDeniedCallbackObjectACE`

The SACL related ACEs:

> - `SystemAuditACE`
> - `SystemAlarmACE`
> - `SystemAuditObjectACE`
> - `SystemAlarmObjectACE`
> - `SystemAuditCallbackACE`
> - `SystemAlarmCallbackACE`
> - `SystemAuditCallbackObjectACE`
> - `SystemAlarmCallbackObjectACE`
> - `SystemMandatoryLabelACE`
> - `SystemResourceAttributeACE`
> - `SystemScopedPolicyIDACE`
> - `SystemProcessTrustLabelACE`

### 5.4.1. Ace classes

#### 5.4.1.1. AccessAllowedACE

class `windows.security.``AccessAllowedACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._ACCESS_ALLOWED_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.2. AccessDeniedACE

class `windows.security.``AccessDeniedACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._ACCESS_DENIED_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.3. AccessAllowedCallbackACE

class `windows.security.``AccessAllowedCallbackACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._ACCESS_ALLOWED_CALLBACK_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.4. AccessDeniedCallbackACE

class `windows.security.``AccessDeniedCallbackACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._ACCESS_DENIED_CALLBACK_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.5. AccessAllowedObjectACE

class `windows.security.``AccessAllowedObjectACE`

  Bases: `windows.security.ObjectRelatedACE`, `windows.generated_def.winstructs._ACCESS_ALLOWED_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `flags`

    The flags of the `ACE`

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

  `inherited_object_type`

    The `InheritedObjectType` described in the ACE. `None` if ACE` has no `InheritedObjectType`

    Type: | `PSID` or `None`

  `mask`

    The list of flags described by the `ACE`

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

  `object_type`

    The `ObjectType` described in the ACE. `None` if ACE` has no `ObjectType`

    Type: | `PSID` or `None`

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.6. AccessDeniedObjectACE

class `windows.security.``AccessDeniedObjectACE`

  Bases: `windows.security.ObjectRelatedACE`, `windows.generated_def.winstructs._ACCESS_DENIED_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `flags`

    The flags of the `ACE`

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

  `inherited_object_type`

    The `InheritedObjectType` described in the ACE. `None` if ACE` has no `InheritedObjectType`

    Type: | `PSID` or `None`

  `mask`

    The list of flags described by the `ACE`

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

  `object_type`

    The `ObjectType` described in the ACE. `None` if ACE` has no `ObjectType`

    Type: | `PSID` or `None`

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.7. AccessAllowedCallbackObjectACE

class `windows.security.``AccessAllowedCallbackObjectACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._ACCESS_ALLOWED_CALLBACK_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.8. AccessDeniedCallbackObjectACE

class `windows.security.``AccessDeniedCallbackObjectACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._ACCESS_DENIED_CALLBACK_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.9. SystemAuditACE

class `windows.security.``SystemAuditACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_AUDIT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.10. SystemAlarmACE

class `windows.security.``SystemAlarmACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_ALARM_ACE`

  reserved for future use.

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.11. SystemAuditObjectACE

class `windows.security.``SystemAuditObjectACE`

  Bases: `windows.security.ObjectRelatedACE`, `windows.generated_def.winstructs._SYSTEM_AUDIT_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `flags`

    The flags of the `ACE`

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

  `inherited_object_type`

    The `InheritedObjectType` described in the ACE. `None` if ACE` has no `InheritedObjectType`

    Type: | `PSID` or `None`

  `mask`

    The list of flags described by the `ACE`

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

  `object_type`

    The `ObjectType` described in the ACE. `None` if ACE` has no `ObjectType`

    Type: | `PSID` or `None`

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.12. SystemAlarmObjectACE

class `windows.security.``SystemAlarmObjectACE`

  Bases: `windows.security.ObjectRelatedACE`, `windows.generated_def.winstructs._SYSTEM_ALARM_OBJECT_ACE`

  reserved for future use.

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `flags`

    The flags of the `ACE`

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

  `inherited_object_type`

    The `InheritedObjectType` described in the ACE. `None` if ACE` has no `InheritedObjectType`

    Type: | `PSID` or `None`

  `mask`

    The list of flags described by the `ACE`

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

  `object_type`

    The `ObjectType` described in the ACE. `None` if ACE` has no `ObjectType`

    Type: | `PSID` or `None`

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.13. SystemAuditCallbackACE

class `windows.security.``SystemAuditCallbackACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._SYSTEM_AUDIT_CALLBACK_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.14. SystemAlarmCallbackACE

class `windows.security.``SystemAlarmCallbackACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._SYSTEM_ALARM_CALLBACK_ACE`

  reserved for future use.

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.15. SystemAuditCallbackObjectACE

class `windows.security.``SystemAuditCallbackObjectACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._SYSTEM_AUDIT_CALLBACK_OBJECT_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.16. SystemAlarmCallbackObjectACE

class `windows.security.``SystemAlarmCallbackObjectACE`

  Bases: `windows.security.CallbackACE`, `windows.generated_def.winstructs._SYSTEM_ALARM_CALLBACK_OBJECT_ACE`

  Reserved for future use

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.17. SystemMandatoryLabelACE

class `windows.security.``SystemMandatoryLabelACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_MANDATORY_LABEL_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.18. SystemResourceAttributeACE

class `windows.security.``SystemResourceAttributeACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_RESOURCE_ATTRIBUTE_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.19. SystemScopedPolicyIDACE

class `windows.security.``SystemScopedPolicyIDACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_SCOPED_POLICY_ID_ACE`

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.1.20. SystemProcessTrustLabelACE

class `windows.security.``SystemProcessTrustLabelACE`

  Bases: `windows.security.MaskAndSidACE`, `windows.generated_def.winstructs._SYSTEM_PROCESS_TRUST_LABEL_ACE`

  Reserved. (from MSDC)

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

### 5.4.2. Ace common base

These classes are internals and here for completness sake. You should not need to instanciate/use them directly.

#### 5.4.2.1. AceHeader

class `windows.security.``AceHeader`

  Improved ACE_HEADER

  `AceType`

    The type of the Ace header

  `flags`

    The flags of the Ace header

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

#### 5.4.2.2. AceBase

class `windows.security.``AceBase`

  Base object for all `ACE` classes. provide access to an improved header

  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

#### 5.4.2.3. MaskAndSidACE

class `windows.security.``MaskAndSidACE`

  Virtual ACE for ACE struct with the following layout:

  - ACE_HEADER Header
  - ACCESS_MASK Mask
  - DWORD SidStart
  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.2.4. CallbackACE

class `windows.security.``CallbackACE`
  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `application_data`

    The application-specific data

    see : https://msdn.microsoft.com/en-us/library/hh877860.aspx

    Type: | `str`

  `mask`

    The list of flags described by the `ACE`

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

  `sid`

    The sid described by the `ACE`

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

#### 5.4.2.5. ObjectRelatedACE

class `windows.security.``ObjectRelatedACE`
  `Header`

    The Header of the `ACE`

    Type: | `AceHeader`

  `flags`

    The flags of the `ACE`

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

  `inherited_object_type`

    The `InheritedObjectType` described in the ACE. `None` if ACE` has no `InheritedObjectType`

    Type: | `PSID` or `None`

  `mask`

    The list of flags described by the `ACE`

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

  `object_type`

    The `ObjectType` described in the ACE. `None` if ACE` has no `ObjectType`

    Type: | `PSID` or `None`

  `sid`

    The sid described by the `ACE`

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