Date:   Mon, 29 Aug 2016 04:47:57 -0700
From:   Sargun Dhillon <sargun@...gun.me>
To:     netdev@...r.kernel.org
Cc:     cgroups@...r.kernel.org, linux-security-module@...r.kernel.org,
        daniel@...earbox.net, ast@...com
Subject: [net-next RFC v2 9/9] doc: Add LSM / BPF Checmate docs

This adds documentation on how to operate, and develop against the
Checmate LSM and Cgroup controller.

Signed-off-by: Sargun Dhillon <sargun@...gun.me>
---
 Documentation/security/Checmate.txt | 54 +++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 Documentation/security/Checmate.txt

diff --git a/Documentation/security/Checmate.txt b/Documentation/security/Checmate.txt
new file mode 100644
index 0000000..d409785
--- /dev/null
+++ b/Documentation/security/Checmate.txt
@@ -0,0 +1,54 @@
+--- What is Checmate? ---
+
+Checmate is a flexible programmable, extensible minor LSM that's coupled with
+cgroups and BPF. It is designed to enforce container-specific policies. By
+default, it does not enforce any policies. It is selectable at build time
+with CONFIG_SECURITY_CHECMATE, and it is controlled through the unified cgroups
+controller hierarchy.
+
+# How to use Checmate
+In order to use Checmate, you have to enable the controller on the cgroup2
+hierarchy. In order to prevent a centralized configuration daemon from mounting
+Checmate on the V1 hierarchy you may want to add 'cgroup_no_v1=checmate' to your
+boot command line.
+
+Enabling the controller:
+	mount -t cgroup2 none $MOUNT_POINT
+	cd $MOUNT_POINT
+	echo +checmate > cgroup.subtree_control
+
+Once you do this, immediate children of this node on the hierarchy will have a
+number of control files that begin with 'checmate.'. Each of these is mapped
+to an LSM hook by the same name. If you read the file, it will return the
+number of filters attached to that given hook. Details of the hooks can be
+found in lsm_hooks.h.
+
+All tasks which are members of a cgroup will have no only the checmate filters
+at that level enforced, but all levels above as well. If there is a need
+to exempt a specific sub-cgroup, a program can use current_task_under_cgroup
+along with a bpf map.
+
+## Adding filters:
+If you would like to add a filter, you must compile a BPF_PROG_TYPE_CHECMATE BPF
+program. You can then write the '%d\n' formatted version of the BPF program
+file descriptor to the relevant control file.
+
+## Removing filters:
+If you would like to remove a specific filter, you can write the negative file
+descriptor of the BPF program to the control file (a la '-%d\n'). If you would
+like to do this, then it is recommended that you pin your programs.
+
+If you would like to remove all filters from a specific hook, simply write '0'
+to the control file. During normal operation, you shouldn't have the bpf syscall
+return '0' for a given program, please take proper precautions to work around
+this.
+
+# Caveats
+## Hook Limit:
+Each hook is limited to having MAX_CHECMATE_INSTANCES (32) hooks per level
+in the hierarchy. The write call will return ENOSPC if you hit this condition.
+
+## CGroup v2 interaction with CGroup v1:
+Because the cgroups subsystem is in transition, using the net_prio or the
+net_classid v1 cgroups will render Checmate inoperable on all network
+hooks that inspect sockets.
\ No newline at end of file
-- 
2.7.4

Powered by blists - more mailing lists