security.unix

Unix security types and uid/gid identity lookups.

Types

Type	Description
`Ace`	Immutable POSIX.1e access-control entry.
`Acl`	Immutable POSIX.1e access-control list.
`Identity`	Unix process identity information for the active VFS target.
`Permission`	POSIX read/write/execute permission bits.
`AceSpec`	A POSIX entry, built or declared as a dictionary. A dictionary has exactly one qualifier key, with the same meaning as the keyword arguments of `ace`.
`AclSpec`	A POSIX ACL, built or given as its entries.
`PermissionBit`	A symbol naming a bit of a `Permission`.
`PermissionSpec`	Permissions given as a `Permission`, one permission symbol, or an iterable of permission symbols.

`AceSpec = (Ace | Dict[{user_obj: PermissionSpec}] | Dict[{group_obj: PermissionSpec}] | Dict[{mask: PermissionSpec}] | Dict[{other: PermissionSpec}] | Dict[{user: Int, ?permissions: PermissionSpec}] | Dict[{group: Int, ?permissions: PermissionSpec}])`

A POSIX entry, built or declared as a dictionary. A dictionary has exactly one qualifier key, with the same meaning as the keyword arguments of ace.

`AclSpec = (Acl | Iterable[AceSpec])`

A POSIX ACL, built or given as its entries.

`PermissionBit = (:READ: | :WRITE: | :EXECUTE:)`

A symbol naming a bit of a Permission.

Symbol	Meaning
`:READ:`	Read permission
`:WRITE:`	Write permission
`:EXECUTE:`	Execute permission

`PermissionSpec = (Permission | PermissionBit | Iterable[PermissionBit])`

Permissions given as a Permission, one permission symbol, or an iterable of permission symbols.

Functions

`ace … -> Ace`

Constructs a POSIX entry from declarative arguments.

Pass exactly one qualifier. user_obj:, group_obj:, mask:, and other: take permissions directly; user: and group: take a numeric ID and accept a separate permissions: value. Named entries default to empty permissions.

Permissions may be a Permission, a permission symbol, or an iterable of permission symbols.

Parameters

Name	Type	Description
`:user_obj?`	`PermissionSpec`	Permissions for the file-owner entry.
`:user?`	`Int`	User ID for a named-user entry.
`:group_obj?`	`PermissionSpec`	Permissions for the file-group entry.
`:group?`	`Int`	Group ID for a named-group entry.
`:mask?`	`PermissionSpec`	Permissions for the effective-rights mask entry.
`:other?`	`PermissionSpec`	Permissions for the entry covering all other users.
`:permissions?`	`PermissionSpec`	Permissions for a `user:` or `group:` entry.

Example

let owner = ace user_obj: [:READ:, :WRITE:]
let named = ace user: 1000 permissions: :READ:

`acl *aces -> Acl`

Constructs a POSIX ACL from entries and declarative entry dictionaries.

The resulting ACL must satisfy the POSIX completeness rules documented by Acl.

Parameters

Name	Type	Description
`*aces`	`AceSpec`	Entries, spread with `...` to pass a collection.

Example

acl
  $ace(user_obj: [:READ:, :WRITE:])
  {group_obj: [:READ:]}
  {other: []}

`group_id name -> Int`

Resolves a Unix group name in the active VFS target.

Parameters

Name	Type	Description
`name`	`Str`	Group name.

Errors

Exception	Condition
`sys.NotFoundError`	The name is unknown
`UnsupportedError`	The active VFS target is not Unix

`group_name gid -> Str`

Resolves a Unix group ID in the active VFS target.

Parameters

Name	Type	Description
`gid`	`(Int \| uuid.Uuid)`	Unix group ID, or on macOS a principal UUID, resolved to a gid first via `security.macos.id_for_uuid`.

Errors

Exception	Condition
`sys.NotFoundError`	The ID is unknown
`UnsupportedError`	The active VFS target is not Unix
`UnsupportedError`	A `uuid.Uuid` is passed on a non-macOS target

`id() -> Identity`

Returns Unix security information captured for the active VFS context.

Errors

Raises UnsupportedError when the active VFS target is not Unix.

Example

let info = id()
echo "uid=$(info.uid) euid=$(info.euid)"

`user_id name -> Int`

Resolves a Unix user name in the active VFS target.

Parameters

Name	Type	Description
`name`	`Str`	User name.

Errors

Exception	Condition
`sys.NotFoundError`	The name is unknown
`UnsupportedError`	The active VFS target is not Unix

`user_name uid -> Str`

Resolves a Unix user ID in the active VFS target.

Parameters

Name	Type	Description
`uid`	`(Int \| uuid.Uuid)`	Unix user ID, or on macOS a principal UUID, resolved to a uid first via `security.macos.id_for_uuid`.

Errors

Exception	Condition
`sys.NotFoundError`	The ID is unknown
`UnsupportedError`	The active VFS target is not Unix
`UnsupportedError`	A `uuid.Uuid` is passed on a non-macOS target