3.9.9 Mount-policy syscall notes

5 min read

These syscall notes preserve the argument and error descriptions from the operator guide. For the kernel contract, use File Descriptor Storage.

3.9.9.1 kacs_set_mount_policy #

The write syscall:

result = kacs_set_mount_policy(fd, args)

Where fd is a file descriptor referring to any object on the target superblock (the kernel uses the fd to identify which superblock — the file itself does not need to be the root of the mount). args is a kacs_mount_policy_args struct:

The kernel:

1. Validates the fd and identifies the superblock.
2. Validates the policy value. Attempts to set KACS_MOUNT_POLICY_UNMANAGED (which is not settable via this ABI) are rejected with -EINVAL.
3. Validates the template SD if provided — must parse, must be within size limits.
4. Checks the caller's privileges. Enabled SeManageVolumePrivilege or SeTcbPrivilege is required, and marking the privilege as used must succeed.
5. Atomically updates the superblock's policy class, the template SD, and increments the generation counter.
6. Writes the new generation to args.generation.
7. Returns 0.

The change is atomic at the superblock level — every future access against any inode on this superblock sees the new policy. There is no transitional state where some inodes are under the old policy and others under the new.

3.9.9.1.1 Privilege requirement #

Changing a mount's policy affects the entire filesystem's access semantics. SeManageVolumePrivilege can author synthesised policy and shadow existing paths; see its authority warning. The SDK wrappers at libpeios de0018bdcaed14abb796aeccec9c8387fd30e452 add no TCB-only gate despite their comments. The command diagnostic also retains a TCB-only hint. Do not automatically grant TCB or globally remap CAP_SYS_ADMIN. A ready-to-use operator interface for changing an existing policy is not established here.

The generated KACS ABI trace table retains the KACS_MP_TCB_DENIED name and TCB-only descriptions. Those labels do not override the source-verified gate; this clarification leaves the generated table unchanged.

3.9.9.1.2 The template SD #

The optional template SD is the default SD used during synthesis when the parent's inheritance does not yield one. The kernel stores the template on the superblock; subsequent synthesis-on-missing calls use it.

The template is a complete self-relative SD — owner, primary group, DACL, optional SACL. The kernel validates the template at policy-set time:

• Must be in self-relative format.
• Must include an owner (an SD without one is malformed and rejected).
• Must fit within 65,535 bytes total; the template specifically is capped at 64 KiB.
• ACLs and ACEs must parse.

A bad template at policy-set time is rejected with -EINVAL; the current policy and template are unchanged.

The template can be omitted entirely (zero pointers) for mounts that don't need one. The synthesis chain then falls through to the hardcoded fallback for any file whose parent doesn't yield an SD.

3.9.9.2 kacs_get_mount_policy #

The read syscall:

result = kacs_get_mount_policy(fd, args)

Same fd and args semantics, returning the current policy class, current template (if buffer provided), and current generation counter.

The kernel:

1. Validates the fd, identifies the superblock.
2. Checks the caller's privileges. Enabled SeManageVolumePrivilege or SeTcbPrivilege is required, with successful privilege-use marking.
3. Writes the policy class, generation, and template to args (template only if a buffer was provided).
4. Returns 0.

Like the write syscall, this uses the pinned-source volume-management gate. A successful policy query does not grant authority to bypass any other mount or file-access checks.

This is the kernel's read-back-the-current-policy interface. A management tool reads the policy, perhaps applies a transformation, and writes the new value back. The read-modify-write pattern is what most policy management code uses.

3.9.9.2.1 Reading the generation #

Compare the value from kacs_get_mount_policy with your earlier read to detect a change. Initial values are implementation-defined, and values from different superblocks are unrelated. The counter identifies changes, not a wall-clock change time. See the kernel administration contract for generation increments and cache invalidation.

3.9.9.3 Errors #

Possible failures from kacs_set_mount_policy:

Possible failures from kacs_get_mount_policy:

In normal operation both calls succeed. Failures are typically privilege issues or malformed inputs.

Edit this page