security.macos

macOS extended access-control-list types and principal identity resolution between Unix uid/gid values and macOS guid_t UUIDs.

Types

Type	Description
`Ace`	Immutable macOS extended access-control entry.
`Acl`	Immutable macOS extended access-control list.
`Flags`	macOS extended ACE inheritance flags.
`Mask`	macOS extended ACE permission bits.
`AceSpec`	A macOS entry, built or declared as a dictionary. A dictionary has exactly one type key, with the same meaning as the keyword arguments of `ace`.
`AclSpec`	A macOS ACL, built or given as its entries.
`FlagBit`	A symbol naming a flag of a `Flags`.
`FlagsSpec`	Flags given as `Flags`, one symbol, or an iterable of symbols.
`MaskBit`	A symbol naming a bit of a `Mask`.
`MaskSpec`	A mask given as a `Mask`, one symbol, or an iterable of symbols.
`Principal`	The principal of an entry, as a UUID or its string or binary form.

`AceSpec = (Ace | Dict[{allow: Principal, mask: MaskSpec, ?flags: FlagsSpec}] | Dict[{deny: Principal, mask: MaskSpec, ?flags: FlagsSpec}])`

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

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

A macOS ACL, built or given as its entries.

`FlagBit = (:FILE_INHERIT: | :DIRECTORY_INHERIT: | :LIMIT_INHERIT: | :ONLY_INHERIT: | :INHERITED:)`

A symbol naming a flag of a Flags.

Symbol	Meaning
`:FILE_INHERIT:`	Files created within a directory inherit this entry
`:DIRECTORY_INHERIT:`	Subdirectories created within a directory inherit this entry
`:LIMIT_INHERIT:`	Stop propagating this entry after one level of inheritance
`:ONLY_INHERIT:`	This entry is inherited but does not apply to the directory itself
`:INHERITED:`	This entry was inherited from a parent directory

`FlagsSpec = (Flags | FlagBit | Iterable[FlagBit])`

Flags given as Flags, one symbol, or an iterable of symbols.

`MaskBit = (:READ_DATA: | :WRITE_DATA: | :EXECUTE: | :DELETE: | :APPEND_DATA: | :DELETE_CHILD: | :READ_ATTRIBUTES: | :WRITE_ATTRIBUTES: | :READ_EXTATTRIBUTES: | :WRITE_EXTATTRIBUTES: | :READ_SECURITY: | :WRITE_SECURITY: | :CHANGE_OWNER: | :SYNCHRONIZE:)`

A symbol naming a bit of a Mask.

Symbol	Meaning
`:READ_DATA:`	Read the file's data, or list a directory
`:WRITE_DATA:`	Write the file's data, or create a file in a directory
`:EXECUTE:`	Execute the file, or traverse a directory
`:DELETE:`	Delete the file or directory
`:APPEND_DATA:`	Append to the file's data, or create a subdirectory
`:DELETE_CHILD:`	Delete a file or directory within a directory
`:READ_ATTRIBUTES:`	Read basic attributes
`:WRITE_ATTRIBUTES:`	Write basic attributes
`:READ_EXTATTRIBUTES:`	Read extended attributes
`:WRITE_EXTATTRIBUTES:`	Write extended attributes
`:READ_SECURITY:`	Read the ACL
`:WRITE_SECURITY:`	Write the ACL
`:CHANGE_OWNER:`	Change owner and owning group
`:SYNCHRONIZE:`	Use synchronous I/O

`MaskSpec = (Mask | MaskBit | Iterable[MaskBit])`

A mask given as a Mask, one symbol, or an iterable of symbols.

`Principal = (uuid.Uuid | Str | Bin)`

The principal of an entry, as a UUID or its string or binary form.

Functions

`ace :mask … -> Ace`

Constructs a macOS entry from declarative arguments.

Pass exactly one of allow: or deny:. Masks and flags accept their built type, one symbol, or an iterable of symbols.

Parameters

Name	Type	Description
`:allow?`	`Principal`	Principal for an `:ALLOW:` entry.
`:deny?`	`Principal`	Principal for a `:DENY:` entry.
`:mask`	`MaskSpec`	Permission mask.
`:flags?`	`FlagsSpec`	Inheritance flags. Defaults to empty.

Example

ace allow: "00112233-4455-6677-8899-aabbccddeeff" mask: [:READ_DATA:]

`acl *aces -> Acl`

Constructs a macOS ACL from entries and declarative entry dictionaries.

An empty ACL is valid.

Parameters

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

`id_for_uuid uuid -> Tuple[:UID: | :GID:, Int]`

Resolves a macOS principal UUID back to the Unix uid or gid it identifies.

The Membership framework reports which kind the UUID resolved to, so the result carries both the ID and whether it names a user or a group.

Parameters

Name	Type	Description
`uuid`	`(uuid.Uuid \| Str \| Bin)`	macOS principal UUID.

Errors

Raises UnsupportedError when the active VFS target is not macOS.

Example

let kind id = id_for_uuid $owner
if (kind == :UID:)
  echo "uid: $id"
else
  echo "gid: $id"

`uuid_for_gid gid -> uuid.Uuid`

Resolves a Unix group ID to its macOS principal UUID.

Parameters

Name	Type	Description
`gid`	`Int`	Unix group ID.

Errors

Raises UnsupportedError when the active VFS target is not macOS.

`uuid_for_uid uid -> uuid.Uuid`

Resolves a Unix user ID to its macOS principal UUID.

Parameters

Name	Type	Description
`uid`	`Int`	Unix user ID.

Errors

Raises UnsupportedError when the active VFS target is not macOS.

Example

let owner = uuid_for_uid 501