Appendix 3.E LSM integration

9 min read

KACS registers as the pkm Linux Security Module. This appendix is an implementation inventory for kernel developers: it describes the storage and call sites behind the contracts in this chapter. These C structures and callbacks are kernel-private, not userspace layouts or extension APIs. The exported ABI remains in §3.A.

The inventory comes from pkm/kacs/lsm.c (pkm_blob_sizes and pkm_hooks[]), the structures in kacs/lsm_internal.h, and the callback implementations listed below. When changing those declarations, update this inventory with the same change. The hook matrix preserves registration order; each row names an actual LSM_HOOK_INIT entry.

3.E.1 Security-blob inventory #

pkm_blob_sizes requests eight sized blob families. Each lbs_* entry is initialized with sizeof the corresponding structure; Linux's LSM infrastructure assigns its offset in the object's security storage. Byte sizes and offsets depend on the build and are not fixed by this manual.

The additional lbs_xattr_count = 1 reserves one xattr-initialization slot. It is not a ninth object blob or a byte-size declaration.

The file blob uses separate u8 managed and u8 delete_on_close fields. There is no flags member or KACS_FILE_FACS_MANAGED constant. The backing-file blob is distinct from the ordinary file blob: its inherited marker records explicit adoption of the outer description's cached grants and continuous-audit mask (§3.9.7).

The task blob reaches process-wide state through its process_state pointer. The refcounted pkm_kacs_process_state contains process_guid, pip_type, pip_trust, one u32 mitigation_bits, the KMES rate bucket, the process_sd reference and process-scoped privilege-audit bookkeeping. It also holds primary_lock, desired_primary_token and primary_epoch, which order primary-token installation across the process's threads (§3.2.3). PIP identity and the process descriptor are not inline task-blob fields; the process mitigations are not nine independent booleans. This shared state is separate from the effective token used during impersonation.

The credential blob's pending_create_sd has the lifetime of an override credential. Overlayfs uses it to stamp the descriptor computed for the original object or caller/parent onto the actual created inode; credential preparation does not inherit it into a derived credential. The task blob's internal SD read/write depth and operation contexts similarly identify specific kernel work; they are not caller-settable authorization flags.

3.E.2 Registered hook matrix #

The current pkm_hooks[] table contains 99 registrations. Paths in the last column are relative to the pkm source repository. A callback's presence here identifies where KACS is called; the operation's access, privilege and lifetime rules remain specified in the relevant chapter.

3.E.3 Direct file-metadata entry points #

An LSM hook receives the arguments supplied by the Linux hook API. Some file-descriptor operations also need the particular open file's cached FACS grant. PKM's patch series therefore calls KACS directly at the file-descriptor call site, before the later inode-level work. These functions are declared and called directly under CONFIG_SECURITY_PKM; they are not additional entries in pkm_hooks[] and are not dispatched through another LSM's hook table.

All seven implementations are in kacs/file_metadata.c. The xattr functions enforce the file's metadata grant as well as the separate rules for protected SD attributes; their names do not make raw SD-xattr access a supported security-descriptor API.

The names security_file_setattr, security_file_getattr, security_file_getxattr and security_file_setxattr do not name hooks provided by this kernel. In particular, do not confuse them with the real inode_file_getattr and inode_file_setattr registrations in the matrix: those receive a dentry and struct file_kattr, not the open file whose cached grant the direct entry points consult. The metadata decision record connects the file-level check to the later inode-level operation. This table covers those file-metadata entry points, not every direct KACS call in PKM's patch series.

3.E.4 Reserved access-mask bits #

RESERVED_ACCESS_MASK_BITS in crates/kacs-core/src/access_mask.rs is 0x0ce0_0000 (bits 21, 22, 23, 26 and 27, counting from zero). It remains a private evaluator constant, not a new UAPI definition. §3.8.10 already specifies the public behavior: reserved bits in a desired mask or any ACE mask reject the check, rather than being ignored. This inventory records the implementation value without adding another exported spelling.

Edit this page