Commit | Line | Data |
---|---|---|
a5606ced KC |
1 | ===== |
2 | Smack | |
3 | ===== | |
e114e473 CS |
4 | |
5 | ||
6 | "Good for you, you've decided to clean the elevator!" | |
7 | - The Elevator, from Dark Star | |
8 | ||
df5cbb27 | 9 | Smack is the Simplified Mandatory Access Control Kernel. |
e114e473 CS |
10 | Smack is a kernel based implementation of mandatory access |
11 | control that includes simplicity in its primary design goals. | |
12 | ||
13 | Smack is not the only Mandatory Access Control scheme | |
14 | available for Linux. Those new to Mandatory Access Control | |
15 | are encouraged to compare Smack with the other mechanisms | |
16 | available to determine which is best suited to the problem | |
17 | at hand. | |
18 | ||
19 | Smack consists of three major components: | |
a5606ced | 20 | |
e114e473 | 21 | - The kernel |
f7112e6c | 22 | - Basic utilities, which are helpful but not required |
e114e473 CS |
23 | - Configuration data |
24 | ||
25 | The kernel component of Smack is implemented as a Linux | |
26 | Security Modules (LSM) module. It requires netlabel and | |
27 | works best with file systems that support extended attributes, | |
28 | although xattr support is not strictly required. | |
29 | It is safe to run a Smack kernel under a "vanilla" distribution. | |
f7112e6c | 30 | |
e114e473 CS |
31 | Smack kernels use the CIPSO IP option. Some network |
32 | configurations are intolerant of IP options and can impede | |
33 | access to systems that use them as Smack does. | |
34 | ||
21abb1ec CS |
35 | Smack is used in the Tizen operating system. Please |
36 | go to http://wiki.tizen.org for information about how | |
37 | Smack is used in Tizen. | |
38 | ||
78a0d8f5 | 39 | The current git repository for Smack user space is: |
e114e473 | 40 | |
78a0d8f5 | 41 | git://github.com/smack-team/smack.git |
e114e473 | 42 | |
78a0d8f5 | 43 | This should make and install on most modern distributions. |
18779b75 | 44 | There are five commands included in smackutil: |
e114e473 | 45 | |
a5606ced KC |
46 | chsmack: |
47 | display or set Smack extended attribute values | |
48 | ||
49 | smackctl: | |
50 | load the Smack access rules | |
51 | ||
52 | smackaccess: | |
53 | report if a process with one label has access | |
54 | to an object with another | |
18779b75 CS |
55 | |
56 | These two commands are obsolete with the introduction of | |
57 | the smackfs/load2 and smackfs/cipso2 interfaces. | |
58 | ||
a5606ced KC |
59 | smackload: |
60 | properly formats data for writing to smackfs/load | |
61 | ||
62 | smackcipso: | |
63 | properly formats data for writing to smackfs/cipso | |
e114e473 CS |
64 | |
65 | In keeping with the intent of Smack, configuration data is | |
66 | minimal and not strictly required. The most important | |
67 | configuration step is mounting the smackfs pseudo filesystem. | |
f7112e6c CS |
68 | If smackutil is installed the startup script will take care |
69 | of this, but it can be manually as well. | |
e114e473 | 70 | |
a5606ced | 71 | Add this line to ``/etc/fstab``:: |
e114e473 | 72 | |
18779b75 | 73 | smackfs /sys/fs/smackfs smackfs defaults 0 0 |
e114e473 | 74 | |
a5606ced | 75 | The ``/sys/fs/smackfs`` directory is created by the kernel. |
e114e473 | 76 | |
f7112e6c CS |
77 | Smack uses extended attributes (xattrs) to store labels on filesystem |
78 | objects. The attributes are stored in the extended attribute security | |
a5606ced | 79 | name space. A process must have ``CAP_MAC_ADMIN`` to change any of these |
f7112e6c CS |
80 | attributes. |
81 | ||
82 | The extended attributes that Smack uses are: | |
83 | ||
84 | SMACK64 | |
85 | Used to make access control decisions. In almost all cases | |
86 | the label given to a new filesystem object will be the label | |
87 | of the process that created it. | |
a5606ced | 88 | |
f7112e6c CS |
89 | SMACK64EXEC |
90 | The Smack label of a process that execs a program file with | |
91 | this attribute set will run with this attribute's value. | |
a5606ced | 92 | |
f7112e6c CS |
93 | SMACK64MMAP |
94 | Don't allow the file to be mmapped by a process whose Smack | |
95 | label does not allow all of the access permitted to a process | |
96 | with the label contained in this attribute. This is a very | |
97 | specific use case for shared libraries. | |
a5606ced | 98 | |
f7112e6c CS |
99 | SMACK64TRANSMUTE |
100 | Can only have the value "TRUE". If this attribute is present | |
101 | on a directory when an object is created in the directory and | |
102 | the Smack rule (more below) that permitted the write access | |
103 | to the directory includes the transmute ("t") mode the object | |
104 | gets the label of the directory instead of the label of the | |
105 | creating process. If the object being created is a directory | |
106 | the SMACK64TRANSMUTE attribute is set as well. | |
a5606ced | 107 | |
f7112e6c CS |
108 | SMACK64IPIN |
109 | This attribute is only available on file descriptors for sockets. | |
110 | Use the Smack label in this attribute for access control | |
111 | decisions on packets being delivered to this socket. | |
a5606ced | 112 | |
f7112e6c CS |
113 | SMACK64IPOUT |
114 | This attribute is only available on file descriptors for sockets. | |
115 | Use the Smack label in this attribute for access control | |
116 | decisions on packets coming from this socket. | |
117 | ||
a5606ced | 118 | There are multiple ways to set a Smack label on a file:: |
e114e473 CS |
119 | |
120 | # attr -S -s SMACK64 -V "value" path | |
f7112e6c | 121 | # chsmack -a value path |
e114e473 | 122 | |
18779b75 | 123 | A process can see the Smack label it is running with by |
a5606ced | 124 | reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN`` |
18779b75 | 125 | can set the process Smack by writing there. |
f7112e6c CS |
126 | |
127 | Most Smack configuration is accomplished by writing to files | |
18779b75 | 128 | in the smackfs filesystem. This pseudo-filesystem is mounted |
a5606ced | 129 | on ``/sys/fs/smackfs``. |
f7112e6c CS |
130 | |
131 | access | |
21abb1ec CS |
132 | Provided for backward compatibility. The access2 interface |
133 | is preferred and should be used instead. | |
f7112e6c CS |
134 | This interface reports whether a subject with the specified |
135 | Smack label has a particular access to an object with a | |
136 | specified Smack label. Write a fixed format access rule to | |
137 | this file. The next read will indicate whether the access | |
138 | would be permitted. The text will be either "1" indicating | |
139 | access, or "0" indicating denial. | |
a5606ced | 140 | |
f7112e6c CS |
141 | access2 |
142 | This interface reports whether a subject with the specified | |
143 | Smack label has a particular access to an object with a | |
144 | specified Smack label. Write a long format access rule to | |
145 | this file. The next read will indicate whether the access | |
146 | would be permitted. The text will be either "1" indicating | |
147 | access, or "0" indicating denial. | |
a5606ced | 148 | |
f7112e6c CS |
149 | ambient |
150 | This contains the Smack label applied to unlabeled network | |
151 | packets. | |
a5606ced | 152 | |
e05b6f98 RK |
153 | change-rule |
154 | This interface allows modification of existing access control rules. | |
a5606ced KC |
155 | The format accepted on write is:: |
156 | ||
e05b6f98 | 157 | "%s %s %s %s" |
a5606ced | 158 | |
e05b6f98 RK |
159 | where the first string is the subject label, the second the |
160 | object label, the third the access to allow and the fourth the | |
161 | access to deny. The access strings may contain only the characters | |
162 | "rwxat-". If a rule for a given subject and object exists it will be | |
163 | modified by enabling the permissions in the third string and disabling | |
164 | those in the fourth string. If there is no such rule it will be | |
165 | created using the access specified in the third and the fourth strings. | |
a5606ced | 166 | |
f7112e6c | 167 | cipso |
21abb1ec CS |
168 | Provided for backward compatibility. The cipso2 interface |
169 | is preferred and should be used instead. | |
f7112e6c | 170 | This interface allows a specific CIPSO header to be assigned |
a5606ced KC |
171 | to a Smack label. The format accepted on write is:: |
172 | ||
f7112e6c | 173 | "%24s%4d%4d"["%4d"]... |
a5606ced | 174 | |
f7112e6c CS |
175 | The first string is a fixed Smack label. The first number is |
176 | the level to use. The second number is the number of categories. | |
a5606ced KC |
177 | The following numbers are the categories:: |
178 | ||
179 | "level-3-cats-5-19 3 2 5 19" | |
180 | ||
f7112e6c CS |
181 | cipso2 |
182 | This interface allows a specific CIPSO header to be assigned | |
a5606ced KC |
183 | to a Smack label. The format accepted on write is:: |
184 | ||
185 | "%s%4d%4d"["%4d"]... | |
186 | ||
f7112e6c CS |
187 | The first string is a long Smack label. The first number is |
188 | the level to use. The second number is the number of categories. | |
a5606ced KC |
189 | The following numbers are the categories:: |
190 | ||
191 | "level-3-cats-5-19 3 2 5 19" | |
192 | ||
f7112e6c CS |
193 | direct |
194 | This contains the CIPSO level used for Smack direct label | |
195 | representation in network packets. | |
a5606ced | 196 | |
f7112e6c CS |
197 | doi |
198 | This contains the CIPSO domain of interpretation used in | |
199 | network packets. | |
a5606ced | 200 | |
21abb1ec CS |
201 | ipv6host |
202 | This interface allows specific IPv6 internet addresses to be | |
203 | treated as single label hosts. Packets are sent to single | |
204 | label hosts only from processes that have Smack write access | |
205 | to the host label. All packets received from single label hosts | |
a5606ced KC |
206 | are given the specified label. The format accepted on write is:: |
207 | ||
21abb1ec CS |
208 | "%h:%h:%h:%h:%h:%h:%h:%h label" or |
209 | "%h:%h:%h:%h:%h:%h:%h:%h/%d label". | |
a5606ced | 210 | |
21abb1ec CS |
211 | The "::" address shortcut is not supported. |
212 | If label is "-DELETE" a matched entry will be deleted. | |
a5606ced | 213 | |
f7112e6c | 214 | load |
21abb1ec CS |
215 | Provided for backward compatibility. The load2 interface |
216 | is preferred and should be used instead. | |
f7112e6c CS |
217 | This interface allows access control rules in addition to |
218 | the system defined rules to be specified. The format accepted | |
a5606ced KC |
219 | on write is:: |
220 | ||
f7112e6c | 221 | "%24s%24s%5s" |
a5606ced | 222 | |
f7112e6c CS |
223 | where the first string is the subject label, the second the |
224 | object label, and the third the requested access. The access | |
225 | string may contain only the characters "rwxat-", and specifies | |
226 | which sort of access is allowed. The "-" is a placeholder for | |
227 | permissions that are not allowed. The string "r-x--" would | |
228 | specify read and execute access. Labels are limited to 23 | |
229 | characters in length. | |
a5606ced | 230 | |
f7112e6c CS |
231 | load2 |
232 | This interface allows access control rules in addition to | |
233 | the system defined rules to be specified. The format accepted | |
a5606ced KC |
234 | on write is:: |
235 | ||
f7112e6c | 236 | "%s %s %s" |
a5606ced | 237 | |
f7112e6c CS |
238 | where the first string is the subject label, the second the |
239 | object label, and the third the requested access. The access | |
240 | string may contain only the characters "rwxat-", and specifies | |
241 | which sort of access is allowed. The "-" is a placeholder for | |
242 | permissions that are not allowed. The string "r-x--" would | |
243 | specify read and execute access. | |
a5606ced | 244 | |
f7112e6c | 245 | load-self |
21abb1ec CS |
246 | Provided for backward compatibility. The load-self2 interface |
247 | is preferred and should be used instead. | |
f7112e6c CS |
248 | This interface allows process specific access rules to be |
249 | defined. These rules are only consulted if access would | |
250 | otherwise be permitted, and are intended to provide additional | |
251 | restrictions on the process. The format is the same as for | |
252 | the load interface. | |
a5606ced | 253 | |
f7112e6c CS |
254 | load-self2 |
255 | This interface allows process specific access rules to be | |
256 | defined. These rules are only consulted if access would | |
257 | otherwise be permitted, and are intended to provide additional | |
258 | restrictions on the process. The format is the same as for | |
259 | the load2 interface. | |
a5606ced | 260 | |
f7112e6c CS |
261 | logging |
262 | This contains the Smack logging state. | |
a5606ced | 263 | |
f7112e6c CS |
264 | mapped |
265 | This contains the CIPSO level used for Smack mapped label | |
266 | representation in network packets. | |
a5606ced | 267 | |
f7112e6c CS |
268 | netlabel |
269 | This interface allows specific internet addresses to be | |
270 | treated as single label hosts. Packets are sent to single | |
271 | label hosts without CIPSO headers, but only from processes | |
272 | that have Smack write access to the host label. All packets | |
273 | received from single label hosts are given the specified | |
a5606ced KC |
274 | label. The format accepted on write is:: |
275 | ||
f7112e6c | 276 | "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label". |
a5606ced | 277 | |
21abb1ec CS |
278 | If the label specified is "-CIPSO" the address is treated |
279 | as a host that supports CIPSO headers. | |
a5606ced | 280 | |
f7112e6c | 281 | onlycap |
c0d77c88 | 282 | This contains labels processes must have for CAP_MAC_ADMIN |
a5606ced | 283 | and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty |
f7112e6c | 284 | these capabilities are effective at for processes with any |
c0d77c88 RK |
285 | label. The values are set by writing the desired labels, separated |
286 | by spaces, to the file or cleared by writing "-" to the file. | |
a5606ced | 287 | |
66867818 LP |
288 | ptrace |
289 | This is used to define the current ptrace policy | |
a5606ced KC |
290 | |
291 | 0 - default: | |
292 | this is the policy that relies on Smack access rules. | |
293 | For the ``PTRACE_READ`` a subject needs to have a read access on | |
294 | object. For the ``PTRACE_ATTACH`` a read-write access is required. | |
295 | ||
296 | 1 - exact: | |
297 | this is the policy that limits ``PTRACE_ATTACH``. Attach is | |
66867818 | 298 | only allowed when subject's and object's labels are equal. |
a5606ced KC |
299 | ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``. |
300 | ||
301 | 2 - draconian: | |
302 | this policy behaves like the 'exact' above with an | |
303 | exception that it can't be overridden with ``CAP_SYS_PTRACE``. | |
304 | ||
449543b0 RK |
305 | revoke-subject |
306 | Writing a Smack label here sets the access to '-' for all access | |
307 | rules with that subject label. | |
a5606ced | 308 | |
18779b75 | 309 | unconfined |
a5606ced KC |
310 | If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP`` |
311 | a process with ``CAP_MAC_ADMIN`` can write a label into this interface. | |
18779b75 CS |
312 | Thereafter, accesses that involve that label will be logged and |
313 | the access permitted if it wouldn't be otherwise. Note that this | |
314 | is dangerous and can ruin the proper labeling of your system. | |
315 | It should never be used in production. | |
a5606ced | 316 | |
38416e53 ZJ |
317 | relabel-self |
318 | This interface contains a list of labels to which the process can | |
a5606ced | 319 | transition to, by writing to ``/proc/self/attr/current``. |
38416e53 | 320 | Normally a process can change its own label to any legal value, but only |
a5606ced KC |
321 | if it has ``CAP_MAC_ADMIN``. This interface allows a process without |
322 | ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list. | |
323 | A process without ``CAP_MAC_ADMIN`` can change its label only once. When it | |
38416e53 ZJ |
324 | does, this list will be cleared. |
325 | The values are set by writing the desired labels, separated | |
326 | by spaces, to the file or cleared by writing "-" to the file. | |
e114e473 | 327 | |
21abb1ec | 328 | If you are using the smackload utility |
a5606ced | 329 | you can add access rules in ``/etc/smack/accesses``. They take the form:: |
e114e473 CS |
330 | |
331 | subjectlabel objectlabel access | |
332 | ||
18779b75 | 333 | access is a combination of the letters rwxatb which specify the |
e114e473 CS |
334 | kind of access permitted a subject with subjectlabel on an |
335 | object with objectlabel. If there is no rule no access is allowed. | |
336 | ||
e114e473 CS |
337 | Look for additional programs on http://schaufler-ca.com |
338 | ||
a5606ced KC |
339 | The Simplified Mandatory Access Control Kernel (Whitepaper) |
340 | =========================================================== | |
e114e473 CS |
341 | |
342 | Casey Schaufler | |
343 | casey@schaufler-ca.com | |
344 | ||
345 | Mandatory Access Control | |
a5606ced | 346 | ------------------------ |
e114e473 CS |
347 | |
348 | Computer systems employ a variety of schemes to constrain how information is | |
349 | shared among the people and services using the machine. Some of these schemes | |
350 | allow the program or user to decide what other programs or users are allowed | |
351 | access to pieces of data. These schemes are called discretionary access | |
352 | control mechanisms because the access control is specified at the discretion | |
353 | of the user. Other schemes do not leave the decision regarding what a user or | |
354 | program can access up to users or programs. These schemes are called mandatory | |
355 | access control mechanisms because you don't have a choice regarding the users | |
356 | or programs that have access to pieces of data. | |
357 | ||
358 | Bell & LaPadula | |
a5606ced | 359 | --------------- |
e114e473 CS |
360 | |
361 | From the middle of the 1980's until the turn of the century Mandatory Access | |
362 | Control (MAC) was very closely associated with the Bell & LaPadula security | |
363 | model, a mathematical description of the United States Department of Defense | |
364 | policy for marking paper documents. MAC in this form enjoyed a following | |
365 | within the Capital Beltway and Scandinavian supercomputer centers but was | |
366 | often sited as failing to address general needs. | |
367 | ||
368 | Domain Type Enforcement | |
a5606ced | 369 | ----------------------- |
e114e473 CS |
370 | |
371 | Around the turn of the century Domain Type Enforcement (DTE) became popular. | |
372 | This scheme organizes users, programs, and data into domains that are | |
373 | protected from each other. This scheme has been widely deployed as a component | |
374 | of popular Linux distributions. The administrative overhead required to | |
375 | maintain this scheme and the detailed understanding of the whole system | |
376 | necessary to provide a secure domain mapping leads to the scheme being | |
377 | disabled or used in limited ways in the majority of cases. | |
378 | ||
379 | Smack | |
a5606ced | 380 | ----- |
e114e473 CS |
381 | |
382 | Smack is a Mandatory Access Control mechanism designed to provide useful MAC | |
383 | while avoiding the pitfalls of its predecessors. The limitations of Bell & | |
384 | LaPadula are addressed by providing a scheme whereby access can be controlled | |
385 | according to the requirements of the system and its purpose rather than those | |
386 | imposed by an arcane government policy. The complexity of Domain Type | |
387 | Enforcement and avoided by defining access controls in terms of the access | |
388 | modes already in use. | |
389 | ||
390 | Smack Terminology | |
a5606ced | 391 | ----------------- |
e114e473 CS |
392 | |
393 | The jargon used to talk about Smack will be familiar to those who have dealt | |
394 | with other MAC systems and shouldn't be too difficult for the uninitiated to | |
395 | pick up. There are four terms that are used in a specific way and that are | |
396 | especially important: | |
397 | ||
a5606ced KC |
398 | Subject: |
399 | A subject is an active entity on the computer system. | |
e114e473 CS |
400 | On Smack a subject is a task, which is in turn the basic unit |
401 | of execution. | |
402 | ||
a5606ced KC |
403 | Object: |
404 | An object is a passive entity on the computer system. | |
e114e473 CS |
405 | On Smack files of all types, IPC, and tasks can be objects. |
406 | ||
a5606ced KC |
407 | Access: |
408 | Any attempt by a subject to put information into or get | |
e114e473 CS |
409 | information from an object is an access. |
410 | ||
a5606ced KC |
411 | Label: |
412 | Data that identifies the Mandatory Access Control | |
e114e473 CS |
413 | characteristics of a subject or an object. |
414 | ||
415 | These definitions are consistent with the traditional use in the security | |
416 | community. There are also some terms from Linux that are likely to crop up: | |
417 | ||
a5606ced KC |
418 | Capability: |
419 | A task that possesses a capability has permission to | |
e114e473 CS |
420 | violate an aspect of the system security policy, as identified by |
421 | the specific capability. A task that possesses one or more | |
422 | capabilities is a privileged task, whereas a task with no | |
423 | capabilities is an unprivileged task. | |
424 | ||
a5606ced KC |
425 | Privilege: |
426 | A task that is allowed to violate the system security | |
e114e473 CS |
427 | policy is said to have privilege. As of this writing a task can |
428 | have privilege either by possessing capabilities or by having an | |
429 | effective user of root. | |
430 | ||
431 | Smack Basics | |
a5606ced | 432 | ------------ |
e114e473 CS |
433 | |
434 | Smack is an extension to a Linux system. It enforces additional restrictions | |
435 | on what subjects can access which objects, based on the labels attached to | |
436 | each of the subject and the object. | |
437 | ||
438 | Labels | |
a5606ced | 439 | ~~~~~~ |
e114e473 | 440 | |
18779b75 CS |
441 | Smack labels are ASCII character strings. They can be up to 255 characters |
442 | long, but keeping them to twenty-three characters is recommended. | |
443 | Single character labels using special characters, that being anything | |
e114e473 CS |
444 | other than a letter or digit, are reserved for use by the Smack development |
445 | team. Smack labels are unstructured, case sensitive, and the only operation | |
446 | ever performed on them is comparison for equality. Smack labels cannot | |
ecfcc53f EB |
447 | contain unprintable characters, the "/" (slash), the "\" (backslash), the "'" |
448 | (quote) and '"' (double-quote) characters. | |
f7112e6c | 449 | Smack labels cannot begin with a '-'. This is reserved for special options. |
e114e473 | 450 | |
a5606ced | 451 | There are some predefined labels:: |
e114e473 | 452 | |
4303154e EB |
453 | _ Pronounced "floor", a single underscore character. |
454 | ^ Pronounced "hat", a single circumflex character. | |
455 | * Pronounced "star", a single asterisk character. | |
456 | ? Pronounced "huh", a single question mark character. | |
f7112e6c | 457 | @ Pronounced "web", a single at sign character. |
e114e473 | 458 | |
18779b75 CS |
459 | Every task on a Smack system is assigned a label. The Smack label |
460 | of a process will usually be assigned by the system initialization | |
461 | mechanism. | |
e114e473 CS |
462 | |
463 | Access Rules | |
a5606ced | 464 | ~~~~~~~~~~~~ |
e114e473 CS |
465 | |
466 | Smack uses the traditional access modes of Linux. These modes are read, | |
467 | execute, write, and occasionally append. There are a few cases where the | |
468 | access mode may not be obvious. These include: | |
469 | ||
a5606ced KC |
470 | Signals: |
471 | A signal is a write operation from the subject task to | |
e114e473 | 472 | the object task. |
a5606ced KC |
473 | |
474 | Internet Domain IPC: | |
475 | Transmission of a packet is considered a | |
e114e473 CS |
476 | write operation from the source task to the destination task. |
477 | ||
478 | Smack restricts access based on the label attached to a subject and the label | |
479 | attached to the object it is trying to access. The rules enforced are, in | |
480 | order: | |
481 | ||
482 | 1. Any access requested by a task labeled "*" is denied. | |
483 | 2. A read or execute access requested by a task labeled "^" | |
484 | is permitted. | |
485 | 3. A read or execute access requested on an object labeled "_" | |
486 | is permitted. | |
487 | 4. Any access requested on an object labeled "*" is permitted. | |
488 | 5. Any access requested by a task on an object with the same | |
489 | label is permitted. | |
490 | 6. Any access requested that is explicitly defined in the loaded | |
491 | rule set is permitted. | |
492 | 7. Any other access is denied. | |
493 | ||
494 | Smack Access Rules | |
a5606ced | 495 | ~~~~~~~~~~~~~~~~~~ |
e114e473 CS |
496 | |
497 | With the isolation provided by Smack access separation is simple. There are | |
498 | many interesting cases where limited access by subjects to objects with | |
499 | different labels is desired. One example is the familiar spy model of | |
500 | sensitivity, where a scientist working on a highly classified project would be | |
501 | able to read documents of lower classifications and anything she writes will | |
502 | be "born" highly classified. To accommodate such schemes Smack includes a | |
503 | mechanism for specifying rules allowing access between labels. | |
504 | ||
505 | Access Rule Format | |
a5606ced | 506 | ~~~~~~~~~~~~~~~~~~ |
e114e473 | 507 | |
a5606ced | 508 | The format of an access rule is:: |
e114e473 CS |
509 | |
510 | subject-label object-label access | |
511 | ||
512 | Where subject-label is the Smack label of the task, object-label is the Smack | |
513 | label of the thing being accessed, and access is a string specifying the sort | |
f7112e6c CS |
514 | of access allowed. The access specification is searched for letters that |
515 | describe access modes: | |
e114e473 CS |
516 | |
517 | a: indicates that append access should be granted. | |
518 | r: indicates that read access should be granted. | |
519 | w: indicates that write access should be granted. | |
520 | x: indicates that execute access should be granted. | |
f7112e6c | 521 | t: indicates that the rule requests transmutation. |
18779b75 | 522 | b: indicates that the rule should be reported for bring-up. |
e114e473 CS |
523 | |
524 | Uppercase values for the specification letters are allowed as well. | |
525 | Access mode specifications can be in any order. Examples of acceptable rules | |
a5606ced | 526 | are:: |
e114e473 CS |
527 | |
528 | TopSecret Secret rx | |
529 | Secret Unclass R | |
530 | Manager Game x | |
531 | User HR w | |
18779b75 | 532 | Snap Crackle rwxatb |
e114e473 CS |
533 | New Old rRrRr |
534 | Closed Off - | |
535 | ||
a5606ced | 536 | Examples of unacceptable rules are:: |
e114e473 CS |
537 | |
538 | Top Secret Secret rx | |
539 | Ace Ace r | |
540 | Odd spells waxbeans | |
541 | ||
542 | Spaces are not allowed in labels. Since a subject always has access to files | |
543 | with the same label specifying a rule for that case is pointless. Only | |
18779b75 | 544 | valid letters (rwxatbRWXATB) and the dash ('-') character are allowed in |
e114e473 CS |
545 | access specifications. The dash is a placeholder, so "a-r" is the same |
546 | as "ar". A lone dash is used to specify that no access should be allowed. | |
547 | ||
548 | Applying Access Rules | |
a5606ced | 549 | ~~~~~~~~~~~~~~~~~~~~~ |
e114e473 CS |
550 | |
551 | The developers of Linux rarely define new sorts of things, usually importing | |
552 | schemes and concepts from other systems. Most often, the other systems are | |
553 | variants of Unix. Unix has many endearing properties, but consistency of | |
554 | access control models is not one of them. Smack strives to treat accesses as | |
555 | uniformly as is sensible while keeping with the spirit of the underlying | |
556 | mechanism. | |
557 | ||
558 | File system objects including files, directories, named pipes, symbolic links, | |
559 | and devices require access permissions that closely match those used by mode | |
560 | bit access. To open a file for reading read access is required on the file. To | |
561 | search a directory requires execute access. Creating a file with write access | |
562 | requires both read and write access on the containing directory. Deleting a | |
563 | file requires read and write access to the file and to the containing | |
564 | directory. It is possible that a user may be able to see that a file exists | |
565 | but not any of its attributes by the circumstance of having read access to the | |
566 | containing directory but not to the differently labeled file. This is an | |
567 | artifact of the file name being data in the directory, not a part of the file. | |
568 | ||
f7112e6c CS |
569 | If a directory is marked as transmuting (SMACK64TRANSMUTE=TRUE) and the |
570 | access rule that allows a process to create an object in that directory | |
571 | includes 't' access the label assigned to the new object will be that | |
572 | of the directory, not the creating process. This makes it much easier | |
573 | for two processes with different labels to share data without granting | |
574 | access to all of their files. | |
575 | ||
e114e473 CS |
576 | IPC objects, message queues, semaphore sets, and memory segments exist in flat |
577 | namespaces and access requests are only required to match the object in | |
578 | question. | |
579 | ||
580 | Process objects reflect tasks on the system and the Smack label used to access | |
581 | them is the same Smack label that the task would use for its own access | |
582 | attempts. Sending a signal via the kill() system call is a write operation | |
583 | from the signaler to the recipient. Debugging a process requires both reading | |
584 | and writing. Creating a new task is an internal operation that results in two | |
585 | tasks with identical Smack labels and requires no access checks. | |
586 | ||
587 | Sockets are data structures attached to processes and sending a packet from | |
588 | one process to another requires that the sender have write access to the | |
589 | receiver. The receiver is not required to have read access to the sender. | |
590 | ||
591 | Setting Access Rules | |
a5606ced | 592 | ~~~~~~~~~~~~~~~~~~~~ |
e114e473 CS |
593 | |
594 | The configuration file /etc/smack/accesses contains the rules to be set at | |
18779b75 CS |
595 | system startup. The contents are written to the special file |
596 | /sys/fs/smackfs/load2. Rules can be added at any time and take effect | |
597 | immediately. For any pair of subject and object labels there can be only | |
598 | one rule, with the most recently specified overriding any earlier | |
599 | specification. | |
e114e473 CS |
600 | |
601 | Task Attribute | |
a5606ced | 602 | ~~~~~~~~~~~~~~ |
e114e473 CS |
603 | |
604 | The Smack label of a process can be read from /proc/<pid>/attr/current. A | |
605 | process can read its own Smack label from /proc/self/attr/current. A | |
606 | privileged process can change its own Smack label by writing to | |
607 | /proc/self/attr/current but not the label of another process. | |
608 | ||
609 | File Attribute | |
a5606ced | 610 | ~~~~~~~~~~~~~~ |
e114e473 CS |
611 | |
612 | The Smack label of a filesystem object is stored as an extended attribute | |
613 | named SMACK64 on the file. This attribute is in the security namespace. It can | |
614 | only be changed by a process with privilege. | |
615 | ||
616 | Privilege | |
a5606ced | 617 | ~~~~~~~~~ |
e114e473 | 618 | |
18779b75 CS |
619 | A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged. |
620 | CAP_MAC_OVERRIDE allows the process access to objects it would | |
621 | be denied otherwise. CAP_MAC_ADMIN allows a process to change | |
622 | Smack data, including rules and attributes. | |
e114e473 CS |
623 | |
624 | Smack Networking | |
a5606ced | 625 | ~~~~~~~~~~~~~~~~ |
e114e473 CS |
626 | |
627 | As mentioned before, Smack enforces access control on network protocol | |
628 | transmissions. Every packet sent by a Smack process is tagged with its Smack | |
629 | label. This is done by adding a CIPSO tag to the header of the IP packet. Each | |
630 | packet received is expected to have a CIPSO tag that identifies the label and | |
631 | if it lacks such a tag the network ambient label is assumed. Before the packet | |
632 | is delivered a check is made to determine that a subject with the label on the | |
633 | packet has write access to the receiving process and if that is not the case | |
634 | the packet is dropped. | |
635 | ||
636 | CIPSO Configuration | |
a5606ced | 637 | ~~~~~~~~~~~~~~~~~~~ |
e114e473 CS |
638 | |
639 | It is normally unnecessary to specify the CIPSO configuration. The default | |
640 | values used by the system handle all internal cases. Smack will compose CIPSO | |
641 | label values to match the Smack labels being used without administrative | |
642 | intervention. Unlabeled packets that come into the system will be given the | |
643 | ambient label. | |
644 | ||
645 | Smack requires configuration in the case where packets from a system that is | |
18779b75 | 646 | not Smack that speaks CIPSO may be encountered. Usually this will be a Trusted |
e114e473 CS |
647 | Solaris system, but there are other, less widely deployed systems out there. |
648 | CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level, | |
649 | and a category set with each packet. The DOI is intended to identify a group | |
650 | of systems that use compatible labeling schemes, and the DOI specified on the | |
18779b75 CS |
651 | Smack system must match that of the remote system or packets will be |
652 | discarded. The DOI is 3 by default. The value can be read from | |
653 | /sys/fs/smackfs/doi and can be changed by writing to /sys/fs/smackfs/doi. | |
e114e473 CS |
654 | |
655 | The label and category set are mapped to a Smack label as defined in | |
656 | /etc/smack/cipso. | |
657 | ||
a5606ced | 658 | A Smack/CIPSO mapping has the form:: |
e114e473 CS |
659 | |
660 | smack level [category [category]*] | |
661 | ||
662 | Smack does not expect the level or category sets to be related in any | |
663 | particular way and does not assume or assign accesses based on them. Some | |
a5606ced | 664 | examples of mappings:: |
e114e473 CS |
665 | |
666 | TopSecret 7 | |
667 | TS:A,B 7 1 2 | |
668 | SecBDE 5 2 4 6 | |
669 | RAFTERS 7 12 26 | |
670 | ||
671 | The ":" and "," characters are permitted in a Smack label but have no special | |
672 | meaning. | |
673 | ||
674 | The mapping of Smack labels to CIPSO values is defined by writing to | |
18779b75 | 675 | /sys/fs/smackfs/cipso2. |
e114e473 CS |
676 | |
677 | In addition to explicit mappings Smack supports direct CIPSO mappings. One | |
678 | CIPSO level is used to indicate that the category set passed in the packet is | |
679 | in fact an encoding of the Smack label. The level used is 250 by default. The | |
18779b75 CS |
680 | value can be read from /sys/fs/smackfs/direct and changed by writing to |
681 | /sys/fs/smackfs/direct. | |
e114e473 CS |
682 | |
683 | Socket Attributes | |
a5606ced | 684 | ~~~~~~~~~~~~~~~~~ |
e114e473 CS |
685 | |
686 | There are two attributes that are associated with sockets. These attributes | |
687 | can only be set by privileged tasks, but any task can read them for their own | |
688 | sockets. | |
689 | ||
a5606ced KC |
690 | SMACK64IPIN: |
691 | The Smack label of the task object. A privileged | |
e114e473 CS |
692 | program that will enforce policy may set this to the star label. |
693 | ||
a5606ced KC |
694 | SMACK64IPOUT: |
695 | The Smack label transmitted with outgoing packets. | |
e114e473 CS |
696 | A privileged program may set this to match the label of another |
697 | task with which it hopes to communicate. | |
698 | ||
4303154e | 699 | Smack Netlabel Exceptions |
a5606ced | 700 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
4303154e EB |
701 | |
702 | You will often find that your labeled application has to talk to the outside, | |
18779b75 | 703 | unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel |
a5606ced KC |
704 | where you can add some exceptions in the form of:: |
705 | ||
706 | @IP1 LABEL1 or | |
707 | @IP2/MASK LABEL2 | |
4303154e EB |
708 | |
709 | It means that your application will have unlabeled access to @IP1 if it has | |
710 | write access on LABEL1, and access to the subnet @IP2/MASK if it has write | |
711 | access on LABEL2. | |
712 | ||
18779b75 CS |
713 | Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask |
714 | first, like in classless IPv4 routing. | |
4303154e | 715 | |
a5606ced | 716 | A special label '@' and an option '-CIPSO' can be used there:: |
4303154e | 717 | |
a5606ced KC |
718 | @ means Internet, any application with any label has access to it |
719 | -CIPSO means standard CIPSO networking | |
720 | ||
721 | If you don't know what CIPSO is and don't plan to use it, you can just do:: | |
722 | ||
723 | echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel | |
724 | echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel | |
4303154e EB |
725 | |
726 | If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled | |
a5606ced | 727 | Internet access, you can have:: |
4303154e | 728 | |
a5606ced KC |
729 | echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel |
730 | echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel | |
731 | echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel | |
4303154e | 732 | |
e114e473 | 733 | Writing Applications for Smack |
a5606ced | 734 | ------------------------------ |
e114e473 CS |
735 | |
736 | There are three sorts of applications that will run on a Smack system. How an | |
737 | application interacts with Smack will determine what it will have to do to | |
738 | work properly under Smack. | |
739 | ||
740 | Smack Ignorant Applications | |
a5606ced | 741 | --------------------------- |
e114e473 CS |
742 | |
743 | By far the majority of applications have no reason whatever to care about the | |
744 | unique properties of Smack. Since invoking a program has no impact on the | |
745 | Smack label associated with the process the only concern likely to arise is | |
746 | whether the process has execute access to the program. | |
747 | ||
748 | Smack Relevant Applications | |
a5606ced | 749 | --------------------------- |
e114e473 CS |
750 | |
751 | Some programs can be improved by teaching them about Smack, but do not make | |
752 | any security decisions themselves. The utility ls(1) is one example of such a | |
753 | program. | |
754 | ||
755 | Smack Enforcing Applications | |
a5606ced | 756 | ---------------------------- |
e114e473 CS |
757 | |
758 | These are special programs that not only know about Smack, but participate in | |
759 | the enforcement of system policy. In most cases these are the programs that | |
760 | set up user sessions. There are also network services that provide information | |
761 | to processes running with various labels. | |
762 | ||
763 | File System Interfaces | |
a5606ced | 764 | ---------------------- |
e114e473 CS |
765 | |
766 | Smack maintains labels on file system objects using extended attributes. The | |
767 | Smack label of a file, directory, or other file system object can be obtained | |
a5606ced | 768 | using getxattr(2):: |
e114e473 CS |
769 | |
770 | len = getxattr("/", "security.SMACK64", value, sizeof (value)); | |
771 | ||
772 | will put the Smack label of the root directory into value. A privileged | |
a5606ced | 773 | process can set the Smack label of a file system object with setxattr(2):: |
e114e473 CS |
774 | |
775 | len = strlen("Rubble"); | |
776 | rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0); | |
777 | ||
778 | will set the Smack label of /foo to "Rubble" if the program has appropriate | |
779 | privilege. | |
780 | ||
781 | Socket Interfaces | |
a5606ced | 782 | ----------------- |
e114e473 CS |
783 | |
784 | The socket attributes can be read using fgetxattr(2). | |
785 | ||
786 | A privileged process can set the Smack label of outgoing packets with | |
a5606ced | 787 | fsetxattr(2):: |
e114e473 CS |
788 | |
789 | len = strlen("Rubble"); | |
790 | rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0); | |
791 | ||
792 | will set the Smack label "Rubble" on packets going out from the socket if the | |
a5606ced | 793 | program has appropriate privilege:: |
e114e473 CS |
794 | |
795 | rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0); | |
796 | ||
797 | will set the Smack label "*" as the object label against which incoming | |
798 | packets will be checked if the program has appropriate privilege. | |
799 | ||
800 | Administration | |
a5606ced | 801 | -------------- |
e114e473 CS |
802 | |
803 | Smack supports some mount options: | |
804 | ||
a5606ced KC |
805 | smackfsdef=label: |
806 | specifies the label to give files that lack | |
e114e473 CS |
807 | the Smack label extended attribute. |
808 | ||
a5606ced KC |
809 | smackfsroot=label: |
810 | specifies the label to assign the root of the | |
e114e473 CS |
811 | file system if it lacks the Smack extended attribute. |
812 | ||
a5606ced KC |
813 | smackfshat=label: |
814 | specifies a label that must have read access to | |
e114e473 CS |
815 | all labels set on the filesystem. Not yet enforced. |
816 | ||
a5606ced KC |
817 | smackfsfloor=label: |
818 | specifies a label to which all labels set on the | |
e114e473 CS |
819 | filesystem must have read access. Not yet enforced. |
820 | ||
55b078f0 JB |
821 | smackfstransmute=label: |
822 | behaves exactly like smackfsroot except that it also | |
823 | sets the transmute flag on the root of the mount | |
824 | ||
e114e473 CS |
825 | These mount options apply to all file system types. |
826 | ||
ecfcc53f | 827 | Smack auditing |
a5606ced | 828 | -------------- |
ecfcc53f EB |
829 | |
830 | If you want Smack auditing of security events, you need to set CONFIG_AUDIT | |
831 | in your kernel configuration. | |
832 | By default, all denied events will be audited. You can change this behavior by | |
a5606ced KC |
833 | writing a single character to the /sys/fs/smackfs/logging file:: |
834 | ||
835 | 0 : no logging | |
836 | 1 : log denied (default) | |
837 | 2 : log accepted | |
838 | 3 : log denied & accepted | |
ecfcc53f EB |
839 | |
840 | Events are logged as 'key=value' pairs, for each event you at least will get | |
40e47125 | 841 | the subject, the object, the rights requested, the action, the kernel function |
ecfcc53f EB |
842 | that triggered the event, plus other pairs depending on the type of event |
843 | audited. | |
18779b75 CS |
844 | |
845 | Bringup Mode | |
a5606ced | 846 | ------------ |
18779b75 CS |
847 | |
848 | Bringup mode provides logging features that can make application | |
849 | configuration and system bringup easier. Configure the kernel with | |
850 | CONFIG_SECURITY_SMACK_BRINGUP to enable these features. When bringup | |
851 | mode is enabled accesses that succeed due to rules marked with the "b" | |
852 | access mode will logged. When a new label is introduced for processes | |
853 | rules can be added aggressively, marked with the "b". The logging allows | |
854 | tracking of which rules actual get used for that label. | |
855 | ||
856 | Another feature of bringup mode is the "unconfined" option. Writing | |
857 | a label to /sys/fs/smackfs/unconfined makes subjects with that label | |
858 | able to access any object, and objects with that label accessible to | |
859 | all subjects. Any access that is granted because a label is unconfined | |
860 | is logged. This feature is dangerous, as files and directories may | |
861 | be created in places they couldn't if the policy were being enforced. |