1 =========================== 1 ===========================
2 Device Whitelist Controller 2 Device Whitelist Controller
3 =========================== 3 ===========================
4 4
5 1. Description 5 1. Description
6 ============== 6 ==============
7 7
8 Implement a cgroup to track and enforce open a 8 Implement a cgroup to track and enforce open and mknod restrictions
9 on device files. A device cgroup associates a 9 on device files. A device cgroup associates a device access
10 whitelist with each cgroup. A whitelist entry 10 whitelist with each cgroup. A whitelist entry has 4 fields.
11 'type' is a (all), c (char), or b (block). 'a 11 'type' is a (all), c (char), or b (block). 'all' means it applies
12 to all types and all major and minor numbers. 12 to all types and all major and minor numbers. Major and minor are
13 either an integer or * for all. Access is a c 13 either an integer or * for all. Access is a composition of r
14 (read), w (write), and m (mknod). 14 (read), w (write), and m (mknod).
15 15
16 The root device cgroup starts with rwm to 'all 16 The root device cgroup starts with rwm to 'all'. A child device
17 cgroup gets a copy of the parent. Administrat 17 cgroup gets a copy of the parent. Administrators can then remove
18 devices from the whitelist or add new entries. 18 devices from the whitelist or add new entries. A child cgroup can
19 never receive a device access which is denied 19 never receive a device access which is denied by its parent.
20 20
21 2. User Interface 21 2. User Interface
22 ================= 22 =================
23 23
24 An entry is added using devices.allow, and rem 24 An entry is added using devices.allow, and removed using
25 devices.deny. For instance:: 25 devices.deny. For instance::
26 26
27 echo 'c 1:3 mr' > /sys/fs/cgroup/1/dev 27 echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
28 28
29 allows cgroup 1 to read and mknod the device u 29 allows cgroup 1 to read and mknod the device usually known as
30 /dev/null. Doing:: 30 /dev/null. Doing::
31 31
32 echo a > /sys/fs/cgroup/1/devices.deny 32 echo a > /sys/fs/cgroup/1/devices.deny
33 33
34 will remove the default 'a *:* rwm' entry. Doi 34 will remove the default 'a *:* rwm' entry. Doing::
35 35
36 echo a > /sys/fs/cgroup/1/devices.allo 36 echo a > /sys/fs/cgroup/1/devices.allow
37 37
38 will add the 'a *:* rwm' entry to the whitelis 38 will add the 'a *:* rwm' entry to the whitelist.
39 39
40 3. Security 40 3. Security
41 =========== 41 ===========
42 42
43 Any task can move itself between cgroups. Thi 43 Any task can move itself between cgroups. This clearly won't
44 suffice, but we can decide the best way to ade 44 suffice, but we can decide the best way to adequately restrict
45 movement as people get some experience with th 45 movement as people get some experience with this. We may just want
46 to require CAP_SYS_ADMIN, which at least is a 46 to require CAP_SYS_ADMIN, which at least is a separate bit from
47 CAP_MKNOD. We may want to just refuse moving 47 CAP_MKNOD. We may want to just refuse moving to a cgroup which
48 isn't a descendant of the current one. Or we 48 isn't a descendant of the current one. Or we may want to use
49 CAP_MAC_ADMIN, since we really are trying to l 49 CAP_MAC_ADMIN, since we really are trying to lock down root.
50 50
51 CAP_SYS_ADMIN is needed to modify the whitelis 51 CAP_SYS_ADMIN is needed to modify the whitelist or move another
52 task to a new cgroup. (Again we'll probably w 52 task to a new cgroup. (Again we'll probably want to change that).
53 53
54 A cgroup may not be granted more permissions t 54 A cgroup may not be granted more permissions than the cgroup's
55 parent has. 55 parent has.
56 56
57 4. Hierarchy 57 4. Hierarchy
58 ============ 58 ============
59 59
60 device cgroups maintain hierarchy by making su 60 device cgroups maintain hierarchy by making sure a cgroup never has more
61 access permissions than its parent. Every tim 61 access permissions than its parent. Every time an entry is written to
62 a cgroup's devices.deny file, all its children 62 a cgroup's devices.deny file, all its children will have that entry removed
63 from their whitelist and all the locally set w 63 from their whitelist and all the locally set whitelist entries will be
64 re-evaluated. In case one of the locally set 64 re-evaluated. In case one of the locally set whitelist entries would provide
65 more access than the cgroup's parent, it'll be 65 more access than the cgroup's parent, it'll be removed from the whitelist.
66 66
67 Example:: 67 Example::
68 68
69 A 69 A
70 / \ 70 / \
71 B 71 B
72 72
73 group behavior exceptions 73 group behavior exceptions
74 A allow "b 8:* rwm", " 74 A allow "b 8:* rwm", "c 116:1 rw"
75 B deny "c 1:3 rwm", " 75 B deny "c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
76 76
77 If a device is denied in group A:: 77 If a device is denied in group A::
78 78
79 # echo "c 116:* r" > A/devices.deny 79 # echo "c 116:* r" > A/devices.deny
80 80
81 it'll propagate down and after revalidating B' 81 it'll propagate down and after revalidating B's entries, the whitelist entry
82 "c 116:2 rwm" will be removed:: 82 "c 116:2 rwm" will be removed::
83 83
84 group whitelist entries 84 group whitelist entries denied devices
85 A all 85 A all "b 8:* rwm", "c 116:* rw"
86 B "c 1:3 rwm", "b 3:* rwm" 86 B "c 1:3 rwm", "b 3:* rwm" all the rest
87 87
88 In case parent's exceptions change and local e 88 In case parent's exceptions change and local exceptions are not allowed
89 anymore, they'll be deleted. 89 anymore, they'll be deleted.
90 90
91 Notice that new whitelist entries will not be 91 Notice that new whitelist entries will not be propagated::
92 92
93 A 93 A
94 / \ 94 / \
95 B 95 B
96 96
97 group whitelist entries 97 group whitelist entries denied devices
98 A "c 1:3 rwm", "c 1:5 r" 98 A "c 1:3 rwm", "c 1:5 r" all the rest
99 B "c 1:3 rwm", "c 1:5 r" 99 B "c 1:3 rwm", "c 1:5 r" all the rest
100 100
101 when adding ``c *:3 rwm``:: 101 when adding ``c *:3 rwm``::
102 102
103 # echo "c *:3 rwm" >A/devices.allow 103 # echo "c *:3 rwm" >A/devices.allow
104 104
105 the result:: 105 the result::
106 106
107 group whitelist entries 107 group whitelist entries denied devices
108 A "c *:3 rwm", "c 1:5 r" 108 A "c *:3 rwm", "c 1:5 r" all the rest
109 B "c 1:3 rwm", "c 1:5 r" 109 B "c 1:3 rwm", "c 1:5 r" all the rest
110 110
111 but now it'll be possible to add new entries t 111 but now it'll be possible to add new entries to B::
112 112
113 # echo "c 2:3 rwm" >B/devices.allow 113 # echo "c 2:3 rwm" >B/devices.allow
114 # echo "c 50:3 r" >B/devices.allow 114 # echo "c 50:3 r" >B/devices.allow
115 115
116 or even:: 116 or even::
117 117
118 # echo "c *:3 rwm" >B/devices.allow 118 # echo "c *:3 rwm" >B/devices.allow
119 119
120 Allowing or denying all by writing 'a' to devi 120 Allowing or denying all by writing 'a' to devices.allow or devices.deny will
121 not be possible once the device cgroups has ch 121 not be possible once the device cgroups has children.
122 122
123 4.1 Hierarchy (internal implementation) 123 4.1 Hierarchy (internal implementation)
124 --------------------------------------- 124 ---------------------------------------
125 125
126 device cgroups is implemented internally using 126 device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
127 list of exceptions. The internal state is con 127 list of exceptions. The internal state is controlled using the same user
128 interface to preserve compatibility with the p 128 interface to preserve compatibility with the previous whitelist-only
129 implementation. Removal or addition of except 129 implementation. Removal or addition of exceptions that will reduce the access
130 to devices will be propagated down the hierarc 130 to devices will be propagated down the hierarchy.
131 For every propagated exception, the effective 131 For every propagated exception, the effective rules will be re-evaluated based
132 on current parent's access rules. 132 on current parent's access rules.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.