Struct ACL

pub struct ACL { /* private fields */ }

ACL represents the access control list (discretionary or oth discretionary/system) for a named object

Implementations

impl ACL

pub fn from_handle( handle: HANDLE, object_type: SE_OBJECT_TYPE, get_sacl: bool, ) -> Result<ACL, DWORD>

Creates an ACL object from a specified object handle.

Arguments

• handle - An object handle.
• object_type - The named object path’s type. See SE_OBJECT_TYPE.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

For file, kernel object, and registry paths, it is better to use the simpler from_file_handle, from_object_handle, and from_registry_handle APIs.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_file_handle(handle: HANDLE, get_sacl: bool) -> Result<ACL, DWORD>

Creates an ACL object from a specified file handle.

Arguments

• handle - A file handle.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_object_handle(handle: HANDLE, get_sacl: bool) -> Result<ACL, DWORD>

Creates an ACL object from a specified kernel object handle.

Arguments

• handle - A kernel object handle.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_registry_handle( handle: HANDLE, is_wow6432key: bool, get_sacl: bool, ) -> Result<ACL, DWORD>

Creates an ACL object from a specified registry handle.

Arguments

• handle - A registry key handle.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_path( path: &str, object_type: SE_OBJECT_TYPE, get_sacl: bool, ) -> Result<ACL, DWORD>

Creates an ACL object from a specified named object path.

Arguments

• path - A string containing the named object path.
• object_type - The named object path’s type. See SE_OBJECT_TYPE.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

For file, kernel object, and registry paths, it is better to use the simpler from_file_path, from_object_path, and from_registry_path APIs.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_file_path(path: &str, get_sacl: bool) -> Result<ACL, DWORD>

Creates an ACL object from a specified file path.

Arguments

• path - A string containing the file path.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_object_path(path: &str, get_sacl: bool) -> Result<ACL, DWORD>

Creates an ACL object from a specified kernel object path.

Arguments

• path - A string containing the kernel object path.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn from_registry_path( path: &str, is_wow6432key: bool, get_sacl: bool, ) -> Result<ACL, DWORD>

Creates an ACL object from a specified registry path.

Arguments

• path - A string containing the registry path.
• get_sacl - A boolean specifying whether the returned ACL object will be able to enumerate and set System ACL entries.

Remarks

This function is a wrapper for from_path.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn object_type(&self) -> ObjectType

Returns the ObjectType of the target named object path as specified during the creation of the ACL object

pub fn all(&self) -> Result<Vec<ACLEntry>, DWORD>

Returns a Vec<ACLEntry> of access control list entries for the specified named object path.

pub fn get( &self, sid: PSID, entry_type: Option<AceType>, ) -> Result<Vec<ACLEntry>, DWORD>

Retrieves a list of access control entries matching the target SID entity and optionally, a access control entry type.

Arguments

• sid - The raw SID of the target entity.
• entry_type - The access control entry type or None.

Errors

On error, a Windows error code is wrapped in an Err type.

pub fn reload(&mut self) -> bool

Update the current named object path’s security descriptor. Returns a boolean denoting the status of the reload operation.

Remarks

This is invoked automatically after any add/remove entry operation.

pub fn add_entry( &mut self, sid: PSID, entry_type: AceType, flags: BYTE, mask: DWORD, ) -> Result<bool, DWORD>

Adds a custom entry into the access control list.

Arguments

• sid - The target entity’s raw SID.
• entry_type - The entry’s type. Currently, only AccessAllow, AccessDeny, SystemAudit, and SystemMandatoryLabel are supported.
• flags - See ACE_HEADER documentation.
• mask - The permissions allotted for the target entity.

Remarks

We only support (for now) adding access allow, access deny, system audit, and system mandatory label entries. After adding the entry, the security descriptor is automatically reloaded to reflect changes.

Errors

On error, a Windows error code is wrapped in an Err type. If the error code is 0, the provided entry_type is invalid.

pub fn remove_entry( &mut self, sid: PSID, entry_type: Option<AceType>, flags: Option<BYTE>, ) -> Result<usize, DWORD>

Removes access control list entries that match the specified parameters.

Arguments

• sid - The target entry’s raw SID.
• entry_type - The entry’s type.
• flags - See ACE_HEADER documentation.

Remarks

After removing the entry, the security descriptor is reloaded automatically to reflect changes.

Errors

On error, a Windows error code wrapped in a Err type.

pub fn allow( &mut self, sid: PSID, inheritable: bool, mask: DWORD, ) -> Result<bool, DWORD>

Adds an access allow entry to the access control list.

Arguments

• sid - The target entity’s raw SID.
• inheritable - Denotes whether this entry should be inheritable by child objects.
• mask - The allowed permissions for the target entity.

Remarks

This is a wrapper over add_entry.

Errors

On error, a Windows error code is wrapped in an Err type. If the error code is 0, the provided entry_type is invalid.

pub fn deny( &mut self, sid: PSID, inheritable: bool, mask: DWORD, ) -> Result<bool, DWORD>

Adds an access deny entry to the access control list.

Arguments

• sid - The target entity’s raw SID.
• inheritable - Denotes whether this entry should be inheritable by child objects.
• mask - The denied permissions for the target entity.

Remarks

This is a wrapper over add_entry

Errors

On error, a Windows error code is wrapped in an Err type. If the error code is 0, the provided entry_type is invalid.

pub fn audit( &mut self, sid: PSID, inheritable: bool, mask: DWORD, audit_success: bool, audit_fails: bool, ) -> Result<bool, DWORD>

Adds a system audit entry to the access control list.

Arguments

• sid - The target entity’s raw SID.
• inheritable - Denotes whether this entry should be inheritable by child objects.
• mask - The permissions to audit.
• audit_success - Denotes that success events should be audited.
• audit_fails - Denotes that failure events should be audited.

Remarks

This is a wrapper over add_entry

Errors

On error, a Windows error code is wrapped in an Err type. If the error code is 0, the provided entry_type is invalid.

pub fn integrity_level( &mut self, label_sid: PSID, inheritable: bool, policy: DWORD, ) -> Result<bool, DWORD>

Adds a system mandatory level entry to the access control list. This sets the mandatory integrity level for the named object path.

Arguments

• label_sid - See pLabelSid in AddMandatoryAce
• inheritable - Denotes whether this entry should be inheritable by child objects.
• policy - See MandatoryPolicy in AddMandatoryAce

Remarks

This is a wrapper over add_entry

Errors

On error, a Windows error code is wrapped in an Err type. If the error code is 0, the provided entry_type is invalid.

pub fn remove( &mut self, sid: PSID, entry_type: Option<AceType>, inheritable: Option<bool>, ) -> Result<usize, DWORD>

Removes access control list entries that match the specified parameters.

Arguments

• sid - The target entry’s raw SID.
• entry_type - The entry’s type.
• inheritable - Denotes whether this entry should be inheritable by child objects.

Remarks

This is a wrapper over remove_entry

Errors

On error, a Windows error code is wrapped in an Err type.

Trait Implementations

impl Debug for ACL

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ACL

fn drop(&mut self)

Executes the destructor for this type.