# 5. windows.security – Security Descriptor & related — PythonForWindows 1.0.4 documentation

# 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 = 7

    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

  property control

    The security descriptor control

    Type:

      `SECURITY_DESCRIPTOR_CONTROL`

  property 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=247)

    Retrieve the security descriptor for the file `filename`

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

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

  from_param()

    Convert a Python object into a function call parameter.

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

    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

  get_owner()

    The owner of the security descriptor

    Type:

      `PSID` or `None`

  property group

    The group of the security descriptor

    Type:

      `PSID` or `None`

  isrelative()

    [WIP] api may change

  make_absolute()

    [WIP] api may change

  make_relative()

    [WIP] api may change

  property owner

    The owner of the security descriptor

    Type:

      `PSID` or `None`

  property revision

    The security descriptor’s revision

    Type:

      `int`

  property 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=247)

    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`

  property 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: `MaskAndSidACE`, `_ACCESS_ALLOWED_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.2. AccessDeniedACE

class windows.security.AccessDeniedACE

  Bases: `MaskAndSidACE`, `_ACCESS_DENIED_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.3. AccessAllowedCallbackACE

class windows.security.AccessAllowedCallbackACE

  Bases: `CallbackACE`, `_ACCESS_ALLOWED_CALLBACK_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.4. AccessDeniedCallbackACE

class windows.security.AccessDeniedCallbackACE

  Bases: `CallbackACE`, `_ACCESS_DENIED_CALLBACK_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.5. AccessAllowedObjectACE

class windows.security.AccessAllowedObjectACE

  Bases: `ObjectRelatedACE`, `_ACCESS_ALLOWED_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property flags

    The flags of the `ACE`

    Type:

      [`int`] - A list of `int`

  property inherited_object_type

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

    Type:

      `PSID` or `None`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property object_type

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

    Type:

      `PSID` or `None`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.6. AccessDeniedObjectACE

class windows.security.AccessDeniedObjectACE

  Bases: `ObjectRelatedACE`, `_ACCESS_DENIED_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property flags

    The flags of the `ACE`

    Type:

      [`int`] - A list of `int`

  property inherited_object_type

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

    Type:

      `PSID` or `None`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property object_type

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

    Type:

      `PSID` or `None`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.7. AccessAllowedCallbackObjectACE

class windows.security.AccessAllowedCallbackObjectACE

  Bases: `CallbackACE`, `_ACCESS_ALLOWED_CALLBACK_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.8. AccessDeniedCallbackObjectACE

class windows.security.AccessDeniedCallbackObjectACE

  Bases: `CallbackACE`, `_ACCESS_DENIED_CALLBACK_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.9. SystemAuditACE

class windows.security.SystemAuditACE

  Bases: `MaskAndSidACE`, `_SYSTEM_AUDIT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.10. SystemAlarmACE

class windows.security.SystemAlarmACE

  Bases: `MaskAndSidACE`, `_SYSTEM_ALARM_ACE`

  reserved for future use.

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.11. SystemAuditObjectACE

class windows.security.SystemAuditObjectACE

  Bases: `ObjectRelatedACE`, `_SYSTEM_AUDIT_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property flags

    The flags of the `ACE`

    Type:

      [`int`] - A list of `int`

  property inherited_object_type

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

    Type:

      `PSID` or `None`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property object_type

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

    Type:

      `PSID` or `None`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.12. SystemAlarmObjectACE

class windows.security.SystemAlarmObjectACE

  Bases: `ObjectRelatedACE`, `_SYSTEM_ALARM_OBJECT_ACE`

  reserved for future use.

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property flags

    The flags of the `ACE`

    Type:

      [`int`] - A list of `int`

  property inherited_object_type

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

    Type:

      `PSID` or `None`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property object_type

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

    Type:

      `PSID` or `None`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.13. SystemAuditCallbackACE

class windows.security.SystemAuditCallbackACE

  Bases: `CallbackACE`, `_SYSTEM_AUDIT_CALLBACK_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.14. SystemAlarmCallbackACE

class windows.security.SystemAlarmCallbackACE

  Bases: `CallbackACE`, `_SYSTEM_ALARM_CALLBACK_ACE`

  reserved for future use.

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.15. SystemAuditCallbackObjectACE

class windows.security.SystemAuditCallbackObjectACE

  Bases: `CallbackACE`, `_SYSTEM_AUDIT_CALLBACK_OBJECT_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.16. SystemAlarmCallbackObjectACE

class windows.security.SystemAlarmCallbackObjectACE

  Bases: `CallbackACE`, `_SYSTEM_ALARM_CALLBACK_OBJECT_ACE`

  Reserved for future use

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.17. SystemMandatoryLabelACE

class windows.security.SystemMandatoryLabelACE

  Bases: `MaskAndSidACE`, `_SYSTEM_MANDATORY_LABEL_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.18. SystemResourceAttributeACE

class windows.security.SystemResourceAttributeACE

  Bases: `MaskAndSidACE`, `_SYSTEM_RESOURCE_ATTRIBUTE_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.19. SystemScopedPolicyIDACE

class windows.security.SystemScopedPolicyIDACE

  Bases: `MaskAndSidACE`, `_SYSTEM_SCOPED_POLICY_ID_ACE`

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.1.20. SystemProcessTrustLabelACE

class windows.security.SystemProcessTrustLabelACE

  Bases: `MaskAndSidACE`, `_SYSTEM_PROCESS_TRUST_LABEL_ACE`

  Reserved. (from MSDC)

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property 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

  property AceType

    The type of the Ace header

  property 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

  property 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

  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.2.4. CallbackACE

class windows.security.CallbackACE
  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property application_data

    The application-specific data

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

    Type:

      `str`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`

#### 5.4.2.5. ObjectRelatedACE

class windows.security.ObjectRelatedACE
  property Header

    The Header of the `ACE`

    Type:

      `AceHeader`

  property flags

    The flags of the `ACE`

    Type:

      [`int`] - A list of `int`

  property inherited_object_type

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

    Type:

      `PSID` or `None`

  property mask

    The list of flags described by the `ACE`

    Type:

      [`int`] - A list of `int`

  property object_type

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

    Type:

      `PSID` or `None`

  property sid

    The sid described by the `ACE`

    Type:

      `windows.generated_def.winstructs.PSID`