0001 ===========================
0002 Device Whitelist Controller
0003 ===========================
0004
0005 1. Description
0006 ==============
0007
0008 Implement a cgroup to track and enforce open and mknod restrictions
0009 on device files. A device cgroup associates a device access
0010 whitelist with each cgroup. A whitelist entry has 4 fields.
0011 'type' is a (all), c (char), or b (block). 'all' means it applies
0012 to all types and all major and minor numbers. Major and minor are
0013 either an integer or * for all. Access is a composition of r
0014 (read), w (write), and m (mknod).
0015
0016 The root device cgroup starts with rwm to 'all'. A child device
0017 cgroup gets a copy of the parent. Administrators can then remove
0018 devices from the whitelist or add new entries. A child cgroup can
0019 never receive a device access which is denied by its parent.
0020
0021 2. User Interface
0022 =================
0023
0024 An entry is added using devices.allow, and removed using
0025 devices.deny. For instance::
0026
0027 echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
0028
0029 allows cgroup 1 to read and mknod the device usually known as
0030 /dev/null. Doing::
0031
0032 echo a > /sys/fs/cgroup/1/devices.deny
0033
0034 will remove the default 'a *:* rwm' entry. Doing::
0035
0036 echo a > /sys/fs/cgroup/1/devices.allow
0037
0038 will add the 'a *:* rwm' entry to the whitelist.
0039
0040 3. Security
0041 ===========
0042
0043 Any task can move itself between cgroups. This clearly won't
0044 suffice, but we can decide the best way to adequately restrict
0045 movement as people get some experience with this. We may just want
0046 to require CAP_SYS_ADMIN, which at least is a separate bit from
0047 CAP_MKNOD. We may want to just refuse moving to a cgroup which
0048 isn't a descendant of the current one. Or we may want to use
0049 CAP_MAC_ADMIN, since we really are trying to lock down root.
0050
0051 CAP_SYS_ADMIN is needed to modify the whitelist or move another
0052 task to a new cgroup. (Again we'll probably want to change that).
0053
0054 A cgroup may not be granted more permissions than the cgroup's
0055 parent has.
0056
0057 4. Hierarchy
0058 ============
0059
0060 device cgroups maintain hierarchy by making sure a cgroup never has more
0061 access permissions than its parent. Every time an entry is written to
0062 a cgroup's devices.deny file, all its children will have that entry removed
0063 from their whitelist and all the locally set whitelist entries will be
0064 re-evaluated. In case one of the locally set whitelist entries would provide
0065 more access than the cgroup's parent, it'll be removed from the whitelist.
0066
0067 Example::
0068
0069 A
0070 / \
0071 B
0072
0073 group behavior exceptions
0074 A allow "b 8:* rwm", "c 116:1 rw"
0075 B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
0076
0077 If a device is denied in group A::
0078
0079 # echo "c 116:* r" > A/devices.deny
0080
0081 it'll propagate down and after revalidating B's entries, the whitelist entry
0082 "c 116:2 rwm" will be removed::
0083
0084 group whitelist entries denied devices
0085 A all "b 8:* rwm", "c 116:* rw"
0086 B "c 1:3 rwm", "b 3:* rwm" all the rest
0087
0088 In case parent's exceptions change and local exceptions are not allowed
0089 anymore, they'll be deleted.
0090
0091 Notice that new whitelist entries will not be propagated::
0092
0093 A
0094 / \
0095 B
0096
0097 group whitelist entries denied devices
0098 A "c 1:3 rwm", "c 1:5 r" all the rest
0099 B "c 1:3 rwm", "c 1:5 r" all the rest
0100
0101 when adding ``c *:3 rwm``::
0102
0103 # echo "c *:3 rwm" >A/devices.allow
0104
0105 the result::
0106
0107 group whitelist entries denied devices
0108 A "c *:3 rwm", "c 1:5 r" all the rest
0109 B "c 1:3 rwm", "c 1:5 r" all the rest
0110
0111 but now it'll be possible to add new entries to B::
0112
0113 # echo "c 2:3 rwm" >B/devices.allow
0114 # echo "c 50:3 r" >B/devices.allow
0115
0116 or even::
0117
0118 # echo "c *:3 rwm" >B/devices.allow
0119
0120 Allowing or denying all by writing 'a' to devices.allow or devices.deny will
0121 not be possible once the device cgroups has children.
0122
0123 4.1 Hierarchy (internal implementation)
0124 ---------------------------------------
0125
0126 device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
0127 list of exceptions. The internal state is controlled using the same user
0128 interface to preserve compatibility with the previous whitelist-only
0129 implementation. Removal or addition of exceptions that will reduce the access
0130 to devices will be propagated down the hierarchy.
0131 For every propagated exception, the effective rules will be re-evaluated based
0132 on current parent's access rules.
