Appendix 3.A KACS ABI Reference

48 min read

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/ by pkm/tools/gen-kacs-abi.py, with struct layouts measured by compiling a probe against the real headers. Regenerate it whenever the ABI changes; do not edit it by hand.

The names here are the ones a program actually compiles against. Everything about the ABI a compiler cannot measure -- token query payload shapes, the specification spellings that differ from these names, what is documented elsewhere, and the kernel configuration -- is in the notes appendix, §3.D, which this generator does not touch.

3.A.1 Syscall numbers #

Signatures are read from the SYSCALL_DEFINE sites in pkm/kacs/.

uapi/pkm/syscall.h also registers the KMES and LCS numbers, 1090–1102, documented in their own chapters.

3.A.2 Structure layouts #

3.A.2.1 struct kacs_query_args #

Total size 16 bytes.

3.A.2.2 struct kacs_adjust_privs_args #

Total size 24 bytes.

3.A.2.3 struct kacs_priv_entry #

Total size 8 bytes.

3.A.2.4 struct kacs_adjust_groups_args #

Total size 144 bytes.

3.A.2.5 struct kacs_duplicate_args #

Total size 16 bytes.

3.A.2.6 struct kacs_group_entry #

Total size 8 bytes.

3.A.2.7 struct kacs_adjust_default_args #

Total size 16 bytes.

3.A.2.8 struct kacs_restrict_args #

Total size 40 bytes.

3.A.2.9 struct kacs_link_tokens_args #

Total size 16 bytes.

3.A.2.10 struct kacs_get_linked_token_args #

Total size 4 bytes.

3.A.2.11 struct kacs_access_check_args #

Total size 136 bytes.

3.A.2.12 struct kacs_object_type_entry #

Total size 20 bytes.

3.A.2.13 struct kacs_node_result #

Total size 8 bytes.

3.A.2.14 struct kacs_open_how #

Total size 32 bytes.

3.A.2.15 struct kacs_mount_policy_args #

Total size 32 bytes.

3.A.2.16 struct kacs_generic_mapping #

Total size 16 bytes.

3.A.3 Token constants #

From uapi/pkm/token.h.

kacs_open_self_token (SYS_KACS_OPEN_SELF_TOKEN) flags.

Per-handle token rights (the low 16 bits of a token access mask).

Token ioctl interface identifier.

kacs_priv_entry.attributes bits.

kacs_adjust_privs bulk-reset flag (not a per-entry attribute).

kacs_restrict_args.flags bits.

Token type (KACS_TOKEN_CLASS_TYPE).

Impersonation level (KACS_TOKEN_CLASS_IMPERSONATION_LEVEL).

Elevation type (KACS_TOKEN_CLASS_ELEVATION_TYPE).

Mandatory-policy bits (KACS_TOKEN_CLASS_MANDATORY_POLICY).

Per-token audit-policy bits — the create-token spec audit_policy field (KACS_TOKEN_SPEC_OFF_AUDIT_POLICY). They select which access-check outcomes the token's object accesses generate audit events for.

Logon type (KACS_TOKEN_CLASS_LOGON_TYPE).

Maximum number of groups a token may carry.

Number of 64-bit words in a group enabled-state bitmask (KACS_TOKEN_MAX_GROUPS / 64).

kacs_create_token (SYS_KACS_CREATE_TOKEN) spec wire format.

The (spec, len) buffer the syscall consumes is a fixed KACS_TOKEN_SPEC_HEADER_BYTES-byte header followed by variable-length sections at header-specified byte offsets. An offset/length (or offset/count) pair that is both zero means the section is absent. Sections may appear in any order; every offset+length is validated to fall within the buffer. The header is not a C struct (it carries packed mixed-width fields and crosses the syscall boundary as raw bytes); read each field at its KACS_TOKEN_SPEC_OFF_* offset. Its fields, in order: __u32 version must be KACS_TOKEN_SPEC_VERSION _u8 token_type KACS_TOKEN_TYPE _u8 impersonation_level KACS_IMLEVEL __u8 _reserved0[2] must be 0 __u32 integrity_rid integrity-level RID _u32 mandatory_policy KACS_TOKEN_MANDATORY_POLICY* bits _u64 privs_present privilege bitmask (KACS_SE*_PRIVILEGE) __u64 privs_enabled initially enabled privileges (subset) __u32 _reserved1 must be 0 (elevation set only by LINK_TOKENS) __u32 projected_uid Linux UID for credential projection __u32 projected_gid Linux GID for credential projection __u32 audit_policy per-token audit flags __u64 expiration expiry timestamp (0 = none) __u64 logon_session_id logon session ID (auth_id) __u32 owner_sid_index 0 = user SID, 1..N = caller group __u32 primary_group_index 0 = user SID, 1..N = caller group __u8 source_name[8] token source name __u64 source_id token source LUID __u32 user_sid_offset byte offset to the user SID __u32 groups_offset byte offset to the groups array __u32 groups_count number of group entries __u32 default_dacl_offset byte offset to the default DACL (0 = none) __u32 default_dacl_len default DACL byte length (0 = none) __u32 user_claims_offset byte offset to user claims (0 = none) __u32 user_claims_len user claims byte length (0 = none) __u32 device_claims_offset byte offset to device claims (0 = none) __u32 device_claims_len device claims byte length (0 = none) __u32 device_groups_offset byte offset to device groups (0 = none) __u32 device_groups_count number of device-group entries (0 = none) __u32 restricted_sids_offset byte offset to restricted SIDs (0 = none) __u32 restricted_sids_count number of restricted-SID entries (0 = none) __u32 confinement_sid_offset byte offset to confinement SID (0 = none) __u32 confinement_sid_len confinement SID byte length (0 = none) __u32 confinement_caps_offset byte offset to confinement caps (0 = none) __u32 confinement_caps_count number of confinement-cap entries (0 = none) __u8 confinement_exempt 1 = exempt from confinement __u8 write_restricted 1 = write-restricted mode __u8 user_deny_only 1 = user SID matches deny ACEs only __u8 isolation_boundary 1 = enable namespace filtering __u32 supp_gids_offset byte offset to supplementary GIDs (0 = none) __u32 supp_gids_count number of supplementary-GID entries (0 = none) __u32 restricted_device_groups_offset byte offset (0 = none) __u32 restricted_device_groups_count entry count (0 = none) __u64 origin originating logon-session LUID (0 = none) __u32 interactivity_scope interactive session number __u32 lcs_credentials_offset byte offset to the LCS extension (0 = none) A group/device-group/restricted- SID/confinement-cap/restricted-device-group entry is [__u32 sid_len][__u8 sid[sid_len]][__u32 attributes]. A supplementary-GIDs section is supp_gids_count little-endian __u32 GIDs. All multi-byte header and section scalars are little-endian.

Byte offsets of the fixed token-spec header fields.

Byte length of the fixed token-source-name field.

Optional LCS registry-credentials extension, located at the token-spec header's lcs_credentials_offset. The section is a fixed KACS_TOKEN_LCS_EXT_HEADER_BYTES-byte header bounded by the next active variable-section offset or the end of the spec; it is consumed exactly (trailing bytes are malformed). Header fields, in order: __u32 version must be KACS_TOKEN_LCS_EXT_VERSION __u32 _reserved must be 0 __u32 scope_count private hive scope GUIDs (<= max) __u32 private_layer_count private layer names (<= max) Payload: scope_count raw 16-byte GUIDs, then private_layer_count little-endian __u32 name byte lengths, then the concatenated UTF-8 layer names. Scope GUIDs must be non-nil and unique; layer names must be 1.. KACS_TOKEN_LCS_MAX_LAYER_NAME_BYTES bytes, must not contain '\', '/', or NUL, and must be unique under case-insensitive matching.

Byte offsets of the fixed LCS-extension header fields.

kacs_create_logon_session (SYS_KACS_CREATE_LOGON_SESSION) spec wire format.

The (spec, len) buffer the syscall consumes is, in order: _u8 logon_type one of KACS_LOGON_TYPE* above __le16 auth_pkg_len byte length of the auth-package name __u8 auth_pkg[auth_pkg_len] auth-package name (valid UTF-8) __le32 user_sid_len byte length of the user SID __u8 user_sid[user_sid_len] binary SID of the authenticated user The buffer is consumed exactly: 7 + auth_pkg_len + user_sid_len must equal len. The kernel assigns the session ID and derives the logon SID from it.

Byte offsets of the fixed-position session-spec fields.

Token-handle ioctls.

Token information classes (kacs_query_args.token_class).

Privileges, as single-bit masks within a token's 64-bit privilege word (present / enabled / enabled-by-default / used are each one such word). Named for the Windows privilege identifiers (SeTcbPrivilege, …).

3.A.4 AccessCheck constants #

From uapi/pkm/access.h.

Full size of kacs_access_check_args the current kernel copies.

Minimum caller_size the kernel accepts (the v1 / v0.20 layout).

Byte size of one kacs_object_type_entry in the object-type tree array.

Largest object-audit-context buffer the kernel accepts.

Largest @Local claims blob the kernel accepts (local_claims_ptr).

Largest object-type tree entry count the kernel accepts.

Claim value types — the discriminant of one attribute in the @Local claims array (local_claims_ptr).

Claim attribute flags.

Central Access Policy (CAAP) spec wire format — the (spec, spec_len) buffer kacs_set_caap (SYS_KACS_SET_CAAP) consumes. A non-empty spec replaces the policy identified by the call's policy SID; a NULL/zero spec removes it. The buffer is a fixed prefix followed by rule_count per-rule sections, and is consumed exactly (trailing bytes are rejected). It is not a C struct (the rule sections are variable-length); read it as raw bytes: __u8 version must be KACS_CAAP_SPEC_VERSION __le32 rule_count number of rules that follow (<= max) rule_count * { __le32 applies_to_len [__u8 applies_to[applies_to_len]] conditional-expression bytecode; 0 = always __le32 effective_dacl_len [__u8 effective_dacl[...]] binary ACL; length MUST be nonzero __le32 effective_sacl_len [__u8 effective_sacl[...]] (0 = none) __le32 staged_dacl_len [__u8 staged_dacl[...]] (0 = none) __le32 staged_sacl_len [__u8 staged_sacl[...]] (0 = none) } Every length- prefixed field uses a little-endian __u32 length and is bounded by KACS_CAAP_MAX_FIELD_BYTES; ACL payloads additionally parse under the security-descriptor size limit (KACS_CAAP_MAX_ACL_BYTES). ACLs use the binary ACL format from <pkm/sd.h>; applies_to is conditional-ACE bytecode.

Byte offsets of the fixed CAAP-spec prefix fields.

Byte length of the fixed CAAP-spec prefix (version + rule_count).

3.A.5 File and open constants #

From uapi/pkm/file.h.

Minimum caller-supplied size accepted for each argument block.

Create dispositions (kacs_open_how.create_disposition).

Create options (kacs_open_how.create_options).

kacs_open_how.flags bits.

File and directory object-specific access rights (the low 16 bits of a file access mask).

The directory aliases name the same bit as the file right it acts as for a directory object.

Mount-policy values (kacs_mount_policy_args.policy).

Status word kacs_open writes back, describing what happened to the file.

3.A.6 Process access rights #

From uapi/pkm/process.h.

KACS process object-specific access rights (the low 16 bits of a process access mask).

Named for the Windows process rights; an access check folds the generic bits (<pkm/sd.h>) into these via the process generic mapping.

3.A.7 Process mitigation bits #

From uapi/pkm/psb.h.

Process Security Block (PSB) process-mitigation bits.

The mitigations argument of kacs_set_psb (SYS_KACS_SET_PSB) is a bitmask of these flags. Setting a bit is activation-backed: KACS either places the target process in the protected state (or verifies it already satisfies the invariant) before committing, and rejects later operations that would disable the protection. Each mitigation is enforced at its own enforcement point and persists across exec. Only the bits in KACS_MIT_ALL are valid; any other bit set in the request is rejected. KACS_MIT_CFI is a legacy alias: requesting it sets both KACS_MIT_CFIF and KACS_MIT_CFIB, and the alias bit itself is not retained.

All valid mitigation bits OR'd together — the accepted-request mask.

3.A.8 Security descriptor constants #

From uapi/pkm/sd.h.

Byte length of the self-relative security-descriptor header.

SECURITY_INFORMATION selector bits — which components of a security descriptor a kacs_get_sd / kacs_set_sd call reads or writes.

SECURITY_DESCRIPTOR_CONTROL bits — the SD header control field.

Access-mask bits — standard rights (bits 16-24) and generic rights (bits 28-31).

The low 16 bits of a mask are object-class specific; see <pkm/file.h> and <pkm/token.h> for those.

ACE types — the ace_type byte of an ACE header (MS-DTYP 2.4.4.1).

ACE header ace_flags byte — inheritance and audit control.

Mandatory-label policy bits — the __le32 access mask of a KACS_ACE_TYPE_SYSTEM_MANDATORY_LABEL ACE. They control which DACL- granted rights a caller whose integrity level does not dominate the object's label (the "up" direction) is denied. Each bit suppresses the rights mapped from the corresponding generic class; unknown bits MUST be ignored.

Object-ACE body Flags field — the __le32 at object-ACE body offset 8, distinct from the 1-byte ace_flags header field above. Indicates which optional GUIDs the object-ACE body carries.

3.A.9 SID constants #

From uapi/pkm/sid.h.

Largest sub_authority_count a valid SID may declare.

Encoded byte length of a SID with the given sub-authority count.

SID_AND_ATTRIBUTES "Attributes" bits (MS-DTYP 2.4.4).

These describe how a group or restricted SID participates in an access check. MS-DTYP names them for groups; they apply to any SID_AND_ATTRIBUTES entry.

3.A.10 Tracepoint diagnostic codes #

From uapi/pkm/trace.h.

kacs_access_decision reason — why a KACS access hook took the return path it did.

Emitted by the kacs:kacs_file_access / _file_open / _native_open _inode_file_access / _inode_permission events. Verdict (allow vs deny) is a separate signal, read from the ret field (0 == allow).

kacs_sd_cache reason — the inode security-descriptor cache outcome.

The lookup miss codes disambiguate the three cache-absent paths that were previously an indistinguishable NULL return (no cache / stale generation missing-but-synthesis-required); the corrupt codes name why a stored SD was rejected. Emitted by kacs:kacs_sd_cache_lookup / _corrupt.

kacs_process_access reason — the outcome of a cross-process access decision (signal, ptrace, scheduler/attribute, prlimit). The reason distinguishes the paths that all surface as -EACCES: an SD denial, a PIP-based denial, a denial rescued (or not) by SeDebugPrivilege, and a PIP-dominance failure. Emitted by kacs:kacs_process_access.

kacs_exec reason — an exec/bprm credential or PIP transition.

Distinguishes the uid/gid-change gate outcomes, the exec primary-token derivation paths and their failures, the exec file integrity-label lookup failures, and the two commit-time transitions. Verdict is the ret field. Emitted by kacs:kacs_exec.

kacs_signing reason — code-signature verification outcomes and the distinct reject reasons of the signing-material probe. Only source enum, verified flag, PIP tier codes, file length, reason, and ret are recorded — never key, signature, xattr, or file bytes. Emitted by kacs:kacs_signing_verify _crypto / _probe.

kacs_socket reason — the outcome of an AF_UNIX socket SD / impersonation hook.

Distinguishes the guard, not-applicable, and verdict paths that otherwise collapse into an indistinguishable -EACCES. Verdict is the ret field. No address, pathname, or SD bytes are recorded.

kacs_namespace stage — which sub-decision of a namespace-mutation hook a record describes.

Single-decision ops report PRIMARY; multi-stage ops (link, rename, delete fallback) tag each distinct verdict. Verdict is the ret field. Never records a pathname. Emitted by the kacs:kacs_inode_* events.

kacs_psb reason — which process-security-baseline path an event marks: mitigation activation (apply) or a W^X / LSV / PIE / prctl-lock enforcement denial. The ok-vs-deny verdict is read from ret. Emitted by kacs:kacs_psb_*.

kacs_token_ioctl cmd — which token-fd ioctl verb a record describes.

The verdict (allow vs deny) is read from the ret field (0 == allow); the access-mask-gate rejections surface as ret == -EACCES. token is an opaque numeric id (never token bytes). Emitted by kacs:kacs_token_ioctl.

kacs_token_ref reason — a token-fd reference lifecycle transition.

TO_FD is a token installed into a fresh anon-inode handle; RELEASE is the handle teardown that drops the token ref; BIND clones a token onto an existing file; OPEN is the checked/fixed-access open path that clones the target token. token is an opaque numeric id, never token bytes. Emitted by kacs:kacs_token_ref.

kacs_logon_session reason — a session/token creation-surface outcome.

The *_DENIED codes name the privilege-gate rejections (the value); the plain op codes mark the successful op. Verdict is also in ret. No token/spec bytes are recorded. Emitted by kacs:kacs_logon_session.

kacs_cred reason — a credential-security lifecycle transition: LSM cred prepare/transfer/alloc/free, explicit token-ref install, the clone-time primary-token lifecycle (CLONE_THREAD share vs fork deep-copy), and the project-linux-cred rejection paths. old_token/new_token are opaque token pointer ids (0 when absent); clone_flags is set only on the clone paths. Verdict/outcome is the ret field. Emitted by kacs:kacs_cred.

kacs_setid reason — the KACS gate on a Linux setid projection (task_fix_setuid / _setgid / setgroups). Each op has two distinct denials that otherwise collapse: NO_TOKEN (-EACCES, no effective subject token) and PRIV_GATE (-EOPNOTSUPP, holder of ASSIGN_PRIMARY_TOKEN privilege). flags is the LSM_SETID* mask (0 for setgroups). Emitted by kacs:kacs_setid.

kacs_task reason — a task-security lifecycle transition.

task_alloc reports a NO_CHILD-mitigation clone block, a process-state inherit ENOMEM, or success; task_free marks teardown. process_state is an opaque process-state pointer id (0 when absent); clone_flags is set on the alloc paths. Outcome is ret. Emitted by kacs:kacs_task.

kacs_primary_install reason — a primary-token / impersonation credential transition.

Distinguishes the install commit, the user-SID-change process-SD reallocation and its ENOMEM, the commit_creds apply, the impersonation override/revert, and the sibling-thread taskwork requeue/failure. old_primary and new_primary are opaque token identity ids (never token bytes). Verdict is the ret field. Emitted by kacs:kacs_primary_install.

kacs_process_token_open reason — the outcome of opening a process/thread primary or effective token (kacs_open_process_token / _thread_token and the proc inspection files). Distinguishes the bad access-mask reject, the no-target-token path, the process access-check denial, the self vs cross inspection verdicts, and the successful open. subject_token/target_token are opaque token identity ids (0 when unknown at the emit site); access_mask is the requested mask. Verdict is ret (>=0 fd == allow). Emitted by kacs:kacs_process_token_open.

kacs_process_state reason — a process-state / process-SD lifecycle or PIP transition.

Covers process-state alloc/free, the CLONE_THREAD share vs fork inheritance split, the no-child clone block, the pending-exec-PIP stage/commit and dumpable hardening, and the process-SD alloc/wrap/replace primitives. process_state is an opaque state-object id (0 when none in scope, e.g. the process-SD primitives); pip_type/pip_trust carry the PIP tier. ret is the outcome (0 == ok). No token or SD bytes. Emitted by kacs:kacs_process_state.

kacs_mount_policy reason — the outcome of a mount-policy set (TCB-gated) or get.

SET_OK marks a committed policy change (generation bumped); the guard codes name the pre-commit rejects that otherwise collapse into a bare -EINVAL/-EOPNOTSUPP/-EPERM. GET_OK/GET_NO_SECURITY are the snapshot paths. Verdict is also in ret. Emitted by kacs:kacs_mount_policy_set / _get.

kacs_sd_syscall target_kind — which SD-bearing object a query/set record describes, resolved by the get_sd/set_sd syscall target-kind fallthrough. ACCESS_CHECK tags the AccessCheck ingress events (kacs_access_check*), whose other scalar fields are 0 at the ingress boundary.

kacs_sd_syscall reason — the outcome of an SD query/set core.

QUERY_OK/SET_OK are the success paths; the remaining codes name the guard / denial paths that otherwise surface as an indistinguishable -EINVAL/-EACCES/-EOPNOTSUPP. Verdict is also in ret. Emitted by kacs:kacs_sd_query / _set.

kacs_access_check reason — the AccessCheck kernel-ingress outcome, above the closed Slice 15 ABI bridge. OK is a completed ingress; the remaining codes name the ingress-time rejects (token-eval-context gate, token resolution, and caap-cache lock acquisition). Verdict is also in ret. Emitted by kacs:kacs_access_check / _list.

kacs_file_snapshot op — which snapshot-grant file operation an event marks.

The allow-vs-deny verdict is read from ret; reason names why a deny path was taken. Emitted by kacs:kacs_file_snapshot (file_access.c).

kacs_file_snapshot reason — why a snapshot-grant op took its return path.

DECISION is the resolved allow/deny (verdict in ret); the remaining codes name the distinct deny causes. Emitted by kacs:kacs_file_snapshot.

kacs_metadata reason — the file-metadata (getattr/setattr/xattr/getsecurity) decision path.

DECISION/CONSUME_HIT/BEGIN_BUSY mark the begin/consume decision lifecycle; the remaining codes name the distinct deny reasons of the xattr setattr hooks. op_class carries the internal PKM_KACS_METADATA_OP_* value; matched is the consume match flag. Emitted by kacs:kacs_metadata (file_metadata.c).

kacs_native_open_ext reason — a widening decision inside the native (kacs_open) create/open machinery. The PREPARE_* codes name the arg- validation reject buckets of pkm_kacs_prepare_native_open; RESOLVE / BUILD_CREATED_SD DELETE_ON_CLOSE_ARM name the later stage outcomes (verdict in ret). Emitted by kacs:kacs_native_open_ext (native_open.c).

kacs_object reason — which object-lifecycle verdict a record marks.

Only the high-value transitions are traced (pure inode/file/sb alloc/free are not). ret is the outcome (0 == ok). Emitted by kacs:kacs_object.

kacs_securityfs reason — which securityfs endpoint path a record marks.

The sessions_read codes disambiguate the deny rungs that otherwise collapse into an errno; open_self / init report the endpoint outcome. Verdict is ret. Emitted by kacs:kacs_securityfs.

kacs_caap reason — which CAAP policy-cache path a record marks.

SET carries the post-set cache_len (an insert grows it; an evict/replace may shrink it); INIT/DESTROY are cache lifecycle; TCB_GATE is the SeTcbPrivilege gate deny. Emitted by kacs:kacs_caap. No SID or spec bytes — lengths only.

kacs_capability reason — the capability->privilege gate verdicts and the capability LSM-hook outcomes. ALLOW_GRANT is an auto-granted allow-cap; HARD_DENY is the SETPCAP/SETFCAP/MAC_OVERRIDE hard block; PRIV_NOT_ENABLED USE_MARK_FAIL are the mapped-privilege gate failures; CAPSET / PRCTL_GUARD CAPABLE / CAPGET report the corresponding hook outcome. Emitted by kacs:kacs_capability. Verdict is ret.

kacs_privilege reason — the require_enabled_privilege gate rungs plus two standalone privilege-path markers. NULL_OR_ZERO is a null- token/zero-mask guard; NOT_ENABLED / USE_MARK_FAIL are the gate failures; CHANGE_NOTIFY marks the open_by_handle_at SeChangeNotifyPrivilege check outcome; RCU_ENOMEM_ FALLBACK marks the deferred-free ENOMEM synchronize_rcu fallback. Emitted by kacs:kacs_privilege. Verdict is ret.

kacs_tlp reason — the trusted-launch-path decisions.

CHECK_PATH marks a no-prefix-match executable-transition deny (path_len

• prefix_count only, NEVER path or prefix bytes); REPLACE marks a prefix-table replacement. Emitted by kacs:kacs_tlp. Verdict is ret.

Edit this page