blob: de5e1aeca7fb95f8a34dff42519a339958aad4ff [file] [log] [blame]
Casey Schauflere114e472008-02-04 22:29:50 -08001
2
3 "Good for you, you've decided to clean the elevator!"
4 - The Elevator, from Dark Star
5
Masanari Iidadf5cbb22014-03-21 10:04:30 +09006Smack is the Simplified Mandatory Access Control Kernel.
Casey Schauflere114e472008-02-04 22:29:50 -08007Smack is a kernel based implementation of mandatory access
8control that includes simplicity in its primary design goals.
9
10Smack is not the only Mandatory Access Control scheme
11available for Linux. Those new to Mandatory Access Control
12are encouraged to compare Smack with the other mechanisms
13available to determine which is best suited to the problem
14at hand.
15
16Smack consists of three major components:
17 - The kernel
Casey Schauflerf7112e62012-05-06 15:22:02 -070018 - Basic utilities, which are helpful but not required
Casey Schauflere114e472008-02-04 22:29:50 -080019 - Configuration data
20
21The kernel component of Smack is implemented as a Linux
22Security Modules (LSM) module. It requires netlabel and
23works best with file systems that support extended attributes,
24although xattr support is not strictly required.
25It is safe to run a Smack kernel under a "vanilla" distribution.
Casey Schauflerf7112e62012-05-06 15:22:02 -070026
Casey Schauflere114e472008-02-04 22:29:50 -080027Smack kernels use the CIPSO IP option. Some network
28configurations are intolerant of IP options and can impede
29access to systems that use them as Smack does.
30
Daniel Wagner78a0d8f2012-09-24 14:21:29 +020031The current git repository for Smack user space is:
Casey Schauflere114e472008-02-04 22:29:50 -080032
Daniel Wagner78a0d8f2012-09-24 14:21:29 +020033 git://github.com/smack-team/smack.git
Casey Schauflere114e472008-02-04 22:29:50 -080034
Daniel Wagner78a0d8f2012-09-24 14:21:29 +020035This should make and install on most modern distributions.
Casey Schaufler18779b72015-03-31 09:49:40 -070036There are five commands included in smackutil:
Casey Schauflere114e472008-02-04 22:29:50 -080037
Casey Schauflerf7112e62012-05-06 15:22:02 -070038chsmack - display or set Smack extended attribute values
Casey Schaufler18779b72015-03-31 09:49:40 -070039smackctl - load the Smack access rules
40smackaccess - report if a process with one label has access
41 to an object with another
42
43These two commands are obsolete with the introduction of
44the smackfs/load2 and smackfs/cipso2 interfaces.
45
46smackload - properly formats data for writing to smackfs/load
47smackcipso - properly formats data for writing to smackfs/cipso
Casey Schauflere114e472008-02-04 22:29:50 -080048
49In keeping with the intent of Smack, configuration data is
50minimal and not strictly required. The most important
51configuration step is mounting the smackfs pseudo filesystem.
Casey Schauflerf7112e62012-05-06 15:22:02 -070052If smackutil is installed the startup script will take care
53of this, but it can be manually as well.
Casey Schauflere114e472008-02-04 22:29:50 -080054
55Add this line to /etc/fstab:
56
Casey Schaufler18779b72015-03-31 09:49:40 -070057 smackfs /sys/fs/smackfs smackfs defaults 0 0
Casey Schauflere114e472008-02-04 22:29:50 -080058
Casey Schaufler18779b72015-03-31 09:49:40 -070059The /sys/fs/smackfs directory is created by the kernel.
Casey Schauflere114e472008-02-04 22:29:50 -080060
Casey Schauflerf7112e62012-05-06 15:22:02 -070061Smack uses extended attributes (xattrs) to store labels on filesystem
62objects. The attributes are stored in the extended attribute security
63name space. A process must have CAP_MAC_ADMIN to change any of these
64attributes.
65
66The extended attributes that Smack uses are:
67
68SMACK64
69 Used to make access control decisions. In almost all cases
70 the label given to a new filesystem object will be the label
71 of the process that created it.
72SMACK64EXEC
73 The Smack label of a process that execs a program file with
74 this attribute set will run with this attribute's value.
75SMACK64MMAP
76 Don't allow the file to be mmapped by a process whose Smack
77 label does not allow all of the access permitted to a process
78 with the label contained in this attribute. This is a very
79 specific use case for shared libraries.
80SMACK64TRANSMUTE
81 Can only have the value "TRUE". If this attribute is present
82 on a directory when an object is created in the directory and
83 the Smack rule (more below) that permitted the write access
84 to the directory includes the transmute ("t") mode the object
85 gets the label of the directory instead of the label of the
86 creating process. If the object being created is a directory
87 the SMACK64TRANSMUTE attribute is set as well.
88SMACK64IPIN
89 This attribute is only available on file descriptors for sockets.
90 Use the Smack label in this attribute for access control
91 decisions on packets being delivered to this socket.
92SMACK64IPOUT
93 This attribute is only available on file descriptors for sockets.
94 Use the Smack label in this attribute for access control
95 decisions on packets coming from this socket.
96
97There are multiple ways to set a Smack label on a file:
Casey Schauflere114e472008-02-04 22:29:50 -080098
99 # attr -S -s SMACK64 -V "value" path
Casey Schauflerf7112e62012-05-06 15:22:02 -0700100 # chsmack -a value path
Casey Schauflere114e472008-02-04 22:29:50 -0800101
Casey Schaufler18779b72015-03-31 09:49:40 -0700102A process can see the Smack label it is running with by
Casey Schauflerf7112e62012-05-06 15:22:02 -0700103reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
Casey Schaufler18779b72015-03-31 09:49:40 -0700104can set the process Smack by writing there.
Casey Schauflere114e472008-02-04 22:29:50 -0800105
Casey Schauflerf7112e62012-05-06 15:22:02 -0700106Most Smack configuration is accomplished by writing to files
Casey Schaufler18779b72015-03-31 09:49:40 -0700107in the smackfs filesystem. This pseudo-filesystem is mounted
108on /sys/fs/smackfs.
Casey Schauflerf7112e62012-05-06 15:22:02 -0700109
110access
111 This interface reports whether a subject with the specified
112 Smack label has a particular access to an object with a
113 specified Smack label. Write a fixed format access rule to
114 this file. The next read will indicate whether the access
115 would be permitted. The text will be either "1" indicating
116 access, or "0" indicating denial.
117access2
118 This interface reports whether a subject with the specified
119 Smack label has a particular access to an object with a
120 specified Smack label. Write a long format access rule to
121 this file. The next read will indicate whether the access
122 would be permitted. The text will be either "1" indicating
123 access, or "0" indicating denial.
124ambient
125 This contains the Smack label applied to unlabeled network
126 packets.
Rafal Krypae05b6f92013-01-10 19:42:00 +0100127change-rule
128 This interface allows modification of existing access control rules.
129 The format accepted on write is:
130 "%s %s %s %s"
131 where the first string is the subject label, the second the
132 object label, the third the access to allow and the fourth the
133 access to deny. The access strings may contain only the characters
134 "rwxat-". If a rule for a given subject and object exists it will be
135 modified by enabling the permissions in the third string and disabling
136 those in the fourth string. If there is no such rule it will be
137 created using the access specified in the third and the fourth strings.
Casey Schauflerf7112e62012-05-06 15:22:02 -0700138cipso
139 This interface allows a specific CIPSO header to be assigned
140 to a Smack label. The format accepted on write is:
141 "%24s%4d%4d"["%4d"]...
142 The first string is a fixed Smack label. The first number is
143 the level to use. The second number is the number of categories.
144 The following numbers are the categories.
145 "level-3-cats-5-19 3 2 5 19"
146cipso2
147 This interface allows a specific CIPSO header to be assigned
148 to a Smack label. The format accepted on write is:
149 "%s%4d%4d"["%4d"]...
150 The first string is a long Smack label. The first number is
151 the level to use. The second number is the number of categories.
152 The following numbers are the categories.
153 "level-3-cats-5-19 3 2 5 19"
154direct
155 This contains the CIPSO level used for Smack direct label
156 representation in network packets.
157doi
158 This contains the CIPSO domain of interpretation used in
159 network packets.
160load
161 This interface allows access control rules in addition to
162 the system defined rules to be specified. The format accepted
163 on write is:
164 "%24s%24s%5s"
165 where the first string is the subject label, the second the
166 object label, and the third the requested access. The access
167 string may contain only the characters "rwxat-", and specifies
168 which sort of access is allowed. The "-" is a placeholder for
169 permissions that are not allowed. The string "r-x--" would
170 specify read and execute access. Labels are limited to 23
171 characters in length.
172load2
173 This interface allows access control rules in addition to
174 the system defined rules to be specified. The format accepted
175 on write is:
176 "%s %s %s"
177 where the first string is the subject label, the second the
178 object label, and the third the requested access. The access
179 string may contain only the characters "rwxat-", and specifies
180 which sort of access is allowed. The "-" is a placeholder for
181 permissions that are not allowed. The string "r-x--" would
182 specify read and execute access.
183load-self
184 This interface allows process specific access rules to be
185 defined. These rules are only consulted if access would
186 otherwise be permitted, and are intended to provide additional
187 restrictions on the process. The format is the same as for
188 the load interface.
189load-self2
190 This interface allows process specific access rules to be
191 defined. These rules are only consulted if access would
192 otherwise be permitted, and are intended to provide additional
193 restrictions on the process. The format is the same as for
194 the load2 interface.
195logging
196 This contains the Smack logging state.
197mapped
198 This contains the CIPSO level used for Smack mapped label
199 representation in network packets.
200netlabel
201 This interface allows specific internet addresses to be
202 treated as single label hosts. Packets are sent to single
203 label hosts without CIPSO headers, but only from processes
204 that have Smack write access to the host label. All packets
205 received from single label hosts are given the specified
206 label. The format accepted on write is:
207 "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
208onlycap
Rafal Krypac0d77c82015-06-02 11:23:48 +0200209 This contains labels processes must have for CAP_MAC_ADMIN
Casey Schauflerf7112e62012-05-06 15:22:02 -0700210 and CAP_MAC_OVERRIDE to be effective. If this file is empty
211 these capabilities are effective at for processes with any
Rafal Krypac0d77c82015-06-02 11:23:48 +0200212 label. The values are set by writing the desired labels, separated
213 by spaces, to the file or cleared by writing "-" to the file.
Lukasz Pawelczyk66867812014-03-11 17:07:06 +0100214ptrace
215 This is used to define the current ptrace policy
Casey Schaufler18779b72015-03-31 09:49:40 -0700216 0 - default: this is the policy that relies on Smack access rules.
Lukasz Pawelczyk66867812014-03-11 17:07:06 +0100217 For the PTRACE_READ a subject needs to have a read access on
218 object. For the PTRACE_ATTACH a read-write access is required.
219 1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is
220 only allowed when subject's and object's labels are equal.
Casey Schaufler18779b72015-03-31 09:49:40 -0700221 PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE.
Lukasz Pawelczyk66867812014-03-11 17:07:06 +0100222 2 - draconian: this policy behaves like the 'exact' above with an
Casey Schaufler18779b72015-03-31 09:49:40 -0700223 exception that it can't be overridden with CAP_SYS_PTRACE.
Rafal Krypa449543b2012-07-11 17:49:30 +0200224revoke-subject
225 Writing a Smack label here sets the access to '-' for all access
226 rules with that subject label.
Casey Schaufler18779b72015-03-31 09:49:40 -0700227unconfined
228 If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP
229 a process with CAP_MAC_ADMIN can write a label into this interface.
230 Thereafter, accesses that involve that label will be logged and
231 the access permitted if it wouldn't be otherwise. Note that this
232 is dangerous and can ruin the proper labeling of your system.
233 It should never be used in production.
Casey Schauflere114e472008-02-04 22:29:50 -0800234
235You can add access rules in /etc/smack/accesses. They take the form:
236
237 subjectlabel objectlabel access
238
Casey Schaufler18779b72015-03-31 09:49:40 -0700239access is a combination of the letters rwxatb which specify the
Casey Schauflere114e472008-02-04 22:29:50 -0800240kind of access permitted a subject with subjectlabel on an
241object with objectlabel. If there is no rule no access is allowed.
242
Casey Schauflere114e472008-02-04 22:29:50 -0800243Look for additional programs on http://schaufler-ca.com
244
245From the Smack Whitepaper:
246
247The Simplified Mandatory Access Control Kernel
248
249Casey Schaufler
250casey@schaufler-ca.com
251
252Mandatory Access Control
253
254Computer systems employ a variety of schemes to constrain how information is
255shared among the people and services using the machine. Some of these schemes
256allow the program or user to decide what other programs or users are allowed
257access to pieces of data. These schemes are called discretionary access
258control mechanisms because the access control is specified at the discretion
259of the user. Other schemes do not leave the decision regarding what a user or
260program can access up to users or programs. These schemes are called mandatory
261access control mechanisms because you don't have a choice regarding the users
262or programs that have access to pieces of data.
263
264Bell & LaPadula
265
266From the middle of the 1980's until the turn of the century Mandatory Access
267Control (MAC) was very closely associated with the Bell & LaPadula security
268model, a mathematical description of the United States Department of Defense
269policy for marking paper documents. MAC in this form enjoyed a following
270within the Capital Beltway and Scandinavian supercomputer centers but was
271often sited as failing to address general needs.
272
273Domain Type Enforcement
274
275Around the turn of the century Domain Type Enforcement (DTE) became popular.
276This scheme organizes users, programs, and data into domains that are
277protected from each other. This scheme has been widely deployed as a component
278of popular Linux distributions. The administrative overhead required to
279maintain this scheme and the detailed understanding of the whole system
280necessary to provide a secure domain mapping leads to the scheme being
281disabled or used in limited ways in the majority of cases.
282
283Smack
284
285Smack is a Mandatory Access Control mechanism designed to provide useful MAC
286while avoiding the pitfalls of its predecessors. The limitations of Bell &
287LaPadula are addressed by providing a scheme whereby access can be controlled
288according to the requirements of the system and its purpose rather than those
289imposed by an arcane government policy. The complexity of Domain Type
290Enforcement and avoided by defining access controls in terms of the access
291modes already in use.
292
293Smack Terminology
294
295The jargon used to talk about Smack will be familiar to those who have dealt
296with other MAC systems and shouldn't be too difficult for the uninitiated to
297pick up. There are four terms that are used in a specific way and that are
298especially important:
299
300 Subject: A subject is an active entity on the computer system.
301 On Smack a subject is a task, which is in turn the basic unit
302 of execution.
303
304 Object: An object is a passive entity on the computer system.
305 On Smack files of all types, IPC, and tasks can be objects.
306
307 Access: Any attempt by a subject to put information into or get
308 information from an object is an access.
309
310 Label: Data that identifies the Mandatory Access Control
311 characteristics of a subject or an object.
312
313These definitions are consistent with the traditional use in the security
314community. There are also some terms from Linux that are likely to crop up:
315
316 Capability: A task that possesses a capability has permission to
317 violate an aspect of the system security policy, as identified by
318 the specific capability. A task that possesses one or more
319 capabilities is a privileged task, whereas a task with no
320 capabilities is an unprivileged task.
321
322 Privilege: A task that is allowed to violate the system security
323 policy is said to have privilege. As of this writing a task can
324 have privilege either by possessing capabilities or by having an
325 effective user of root.
326
327Smack Basics
328
329Smack is an extension to a Linux system. It enforces additional restrictions
330on what subjects can access which objects, based on the labels attached to
331each of the subject and the object.
332
333Labels
334
Casey Schaufler18779b72015-03-31 09:49:40 -0700335Smack labels are ASCII character strings. They can be up to 255 characters
336long, but keeping them to twenty-three characters is recommended.
337Single character labels using special characters, that being anything
Casey Schauflere114e472008-02-04 22:29:50 -0800338other than a letter or digit, are reserved for use by the Smack development
339team. Smack labels are unstructured, case sensitive, and the only operation
340ever performed on them is comparison for equality. Smack labels cannot
Etienne Bassetecfcc532009-04-08 20:40:06 +0200341contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
342(quote) and '"' (double-quote) characters.
Casey Schauflerf7112e62012-05-06 15:22:02 -0700343Smack labels cannot begin with a '-'. This is reserved for special options.
Casey Schauflere114e472008-02-04 22:29:50 -0800344
345There are some predefined labels:
346
Etienne Basset43031542009-03-27 17:11:01 -0400347 _ Pronounced "floor", a single underscore character.
348 ^ Pronounced "hat", a single circumflex character.
349 * Pronounced "star", a single asterisk character.
350 ? Pronounced "huh", a single question mark character.
Casey Schauflerf7112e62012-05-06 15:22:02 -0700351 @ Pronounced "web", a single at sign character.
Casey Schauflere114e472008-02-04 22:29:50 -0800352
Casey Schaufler18779b72015-03-31 09:49:40 -0700353Every task on a Smack system is assigned a label. The Smack label
354of a process will usually be assigned by the system initialization
355mechanism.
Casey Schauflere114e472008-02-04 22:29:50 -0800356
357Access Rules
358
359Smack uses the traditional access modes of Linux. These modes are read,
360execute, write, and occasionally append. There are a few cases where the
361access mode may not be obvious. These include:
362
363 Signals: A signal is a write operation from the subject task to
364 the object task.
365 Internet Domain IPC: Transmission of a packet is considered a
366 write operation from the source task to the destination task.
367
368Smack restricts access based on the label attached to a subject and the label
369attached to the object it is trying to access. The rules enforced are, in
370order:
371
372 1. Any access requested by a task labeled "*" is denied.
373 2. A read or execute access requested by a task labeled "^"
374 is permitted.
375 3. A read or execute access requested on an object labeled "_"
376 is permitted.
377 4. Any access requested on an object labeled "*" is permitted.
378 5. Any access requested by a task on an object with the same
379 label is permitted.
380 6. Any access requested that is explicitly defined in the loaded
381 rule set is permitted.
382 7. Any other access is denied.
383
384Smack Access Rules
385
386With the isolation provided by Smack access separation is simple. There are
387many interesting cases where limited access by subjects to objects with
388different labels is desired. One example is the familiar spy model of
389sensitivity, where a scientist working on a highly classified project would be
390able to read documents of lower classifications and anything she writes will
391be "born" highly classified. To accommodate such schemes Smack includes a
392mechanism for specifying rules allowing access between labels.
393
394Access Rule Format
395
396The format of an access rule is:
397
398 subject-label object-label access
399
400Where subject-label is the Smack label of the task, object-label is the Smack
401label of the thing being accessed, and access is a string specifying the sort
Casey Schauflerf7112e62012-05-06 15:22:02 -0700402of access allowed. The access specification is searched for letters that
403describe access modes:
Casey Schauflere114e472008-02-04 22:29:50 -0800404
405 a: indicates that append access should be granted.
406 r: indicates that read access should be granted.
407 w: indicates that write access should be granted.
408 x: indicates that execute access should be granted.
Casey Schauflerf7112e62012-05-06 15:22:02 -0700409 t: indicates that the rule requests transmutation.
Casey Schaufler18779b72015-03-31 09:49:40 -0700410 b: indicates that the rule should be reported for bring-up.
Casey Schauflere114e472008-02-04 22:29:50 -0800411
412Uppercase values for the specification letters are allowed as well.
413Access mode specifications can be in any order. Examples of acceptable rules
414are:
415
416 TopSecret Secret rx
417 Secret Unclass R
418 Manager Game x
419 User HR w
Casey Schaufler18779b72015-03-31 09:49:40 -0700420 Snap Crackle rwxatb
Casey Schauflere114e472008-02-04 22:29:50 -0800421 New Old rRrRr
422 Closed Off -
423
424Examples of unacceptable rules are:
425
426 Top Secret Secret rx
427 Ace Ace r
428 Odd spells waxbeans
429
430Spaces are not allowed in labels. Since a subject always has access to files
431with the same label specifying a rule for that case is pointless. Only
Casey Schaufler18779b72015-03-31 09:49:40 -0700432valid letters (rwxatbRWXATB) and the dash ('-') character are allowed in
Casey Schauflere114e472008-02-04 22:29:50 -0800433access specifications. The dash is a placeholder, so "a-r" is the same
434as "ar". A lone dash is used to specify that no access should be allowed.
435
436Applying Access Rules
437
438The developers of Linux rarely define new sorts of things, usually importing
439schemes and concepts from other systems. Most often, the other systems are
440variants of Unix. Unix has many endearing properties, but consistency of
441access control models is not one of them. Smack strives to treat accesses as
442uniformly as is sensible while keeping with the spirit of the underlying
443mechanism.
444
445File system objects including files, directories, named pipes, symbolic links,
446and devices require access permissions that closely match those used by mode
447bit access. To open a file for reading read access is required on the file. To
448search a directory requires execute access. Creating a file with write access
449requires both read and write access on the containing directory. Deleting a
450file requires read and write access to the file and to the containing
451directory. It is possible that a user may be able to see that a file exists
452but not any of its attributes by the circumstance of having read access to the
453containing directory but not to the differently labeled file. This is an
454artifact of the file name being data in the directory, not a part of the file.
455
Casey Schauflerf7112e62012-05-06 15:22:02 -0700456If a directory is marked as transmuting (SMACK64TRANSMUTE=TRUE) and the
457access rule that allows a process to create an object in that directory
458includes 't' access the label assigned to the new object will be that
459of the directory, not the creating process. This makes it much easier
460for two processes with different labels to share data without granting
461access to all of their files.
462
Casey Schauflere114e472008-02-04 22:29:50 -0800463IPC objects, message queues, semaphore sets, and memory segments exist in flat
464namespaces and access requests are only required to match the object in
465question.
466
467Process objects reflect tasks on the system and the Smack label used to access
468them is the same Smack label that the task would use for its own access
469attempts. Sending a signal via the kill() system call is a write operation
470from the signaler to the recipient. Debugging a process requires both reading
471and writing. Creating a new task is an internal operation that results in two
472tasks with identical Smack labels and requires no access checks.
473
474Sockets are data structures attached to processes and sending a packet from
475one process to another requires that the sender have write access to the
476receiver. The receiver is not required to have read access to the sender.
477
478Setting Access Rules
479
480The configuration file /etc/smack/accesses contains the rules to be set at
Casey Schaufler18779b72015-03-31 09:49:40 -0700481system startup. The contents are written to the special file
482/sys/fs/smackfs/load2. Rules can be added at any time and take effect
483immediately. For any pair of subject and object labels there can be only
484one rule, with the most recently specified overriding any earlier
485specification.
Casey Schauflere114e472008-02-04 22:29:50 -0800486
487Task Attribute
488
489The Smack label of a process can be read from /proc/<pid>/attr/current. A
490process can read its own Smack label from /proc/self/attr/current. A
491privileged process can change its own Smack label by writing to
492/proc/self/attr/current but not the label of another process.
493
494File Attribute
495
496The Smack label of a filesystem object is stored as an extended attribute
497named SMACK64 on the file. This attribute is in the security namespace. It can
498only be changed by a process with privilege.
499
500Privilege
501
Casey Schaufler18779b72015-03-31 09:49:40 -0700502A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
503CAP_MAC_OVERRIDE allows the process access to objects it would
504be denied otherwise. CAP_MAC_ADMIN allows a process to change
505Smack data, including rules and attributes.
Casey Schauflere114e472008-02-04 22:29:50 -0800506
507Smack Networking
508
509As mentioned before, Smack enforces access control on network protocol
510transmissions. Every packet sent by a Smack process is tagged with its Smack
511label. This is done by adding a CIPSO tag to the header of the IP packet. Each
512packet received is expected to have a CIPSO tag that identifies the label and
513if it lacks such a tag the network ambient label is assumed. Before the packet
514is delivered a check is made to determine that a subject with the label on the
515packet has write access to the receiving process and if that is not the case
516the packet is dropped.
517
518CIPSO Configuration
519
520It is normally unnecessary to specify the CIPSO configuration. The default
521values used by the system handle all internal cases. Smack will compose CIPSO
522label values to match the Smack labels being used without administrative
523intervention. Unlabeled packets that come into the system will be given the
524ambient label.
525
526Smack requires configuration in the case where packets from a system that is
Casey Schaufler18779b72015-03-31 09:49:40 -0700527not Smack that speaks CIPSO may be encountered. Usually this will be a Trusted
Casey Schauflere114e472008-02-04 22:29:50 -0800528Solaris system, but there are other, less widely deployed systems out there.
529CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level,
530and a category set with each packet. The DOI is intended to identify a group
531of systems that use compatible labeling schemes, and the DOI specified on the
Casey Schaufler18779b72015-03-31 09:49:40 -0700532Smack system must match that of the remote system or packets will be
533discarded. The DOI is 3 by default. The value can be read from
534/sys/fs/smackfs/doi and can be changed by writing to /sys/fs/smackfs/doi.
Casey Schauflere114e472008-02-04 22:29:50 -0800535
536The label and category set are mapped to a Smack label as defined in
537/etc/smack/cipso.
538
539A Smack/CIPSO mapping has the form:
540
541 smack level [category [category]*]
542
543Smack does not expect the level or category sets to be related in any
544particular way and does not assume or assign accesses based on them. Some
545examples of mappings:
546
547 TopSecret 7
548 TS:A,B 7 1 2
549 SecBDE 5 2 4 6
550 RAFTERS 7 12 26
551
552The ":" and "," characters are permitted in a Smack label but have no special
553meaning.
554
555The mapping of Smack labels to CIPSO values is defined by writing to
Casey Schaufler18779b72015-03-31 09:49:40 -0700556/sys/fs/smackfs/cipso2.
Casey Schauflere114e472008-02-04 22:29:50 -0800557
558In addition to explicit mappings Smack supports direct CIPSO mappings. One
559CIPSO level is used to indicate that the category set passed in the packet is
560in fact an encoding of the Smack label. The level used is 250 by default. The
Casey Schaufler18779b72015-03-31 09:49:40 -0700561value can be read from /sys/fs/smackfs/direct and changed by writing to
562/sys/fs/smackfs/direct.
Casey Schauflere114e472008-02-04 22:29:50 -0800563
564Socket Attributes
565
566There are two attributes that are associated with sockets. These attributes
567can only be set by privileged tasks, but any task can read them for their own
568sockets.
569
570 SMACK64IPIN: The Smack label of the task object. A privileged
571 program that will enforce policy may set this to the star label.
572
573 SMACK64IPOUT: The Smack label transmitted with outgoing packets.
574 A privileged program may set this to match the label of another
575 task with which it hopes to communicate.
576
Etienne Basset43031542009-03-27 17:11:01 -0400577Smack Netlabel Exceptions
578
579You will often find that your labeled application has to talk to the outside,
Casey Schaufler18779b72015-03-31 09:49:40 -0700580unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
581where you can add some exceptions in the form of :
Etienne Basset43031542009-03-27 17:11:01 -0400582@IP1 LABEL1 or
583@IP2/MASK LABEL2
584
585It means that your application will have unlabeled access to @IP1 if it has
586write access on LABEL1, and access to the subnet @IP2/MASK if it has write
587access on LABEL2.
588
Casey Schaufler18779b72015-03-31 09:49:40 -0700589Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
590first, like in classless IPv4 routing.
Etienne Basset43031542009-03-27 17:11:01 -0400591
592A special label '@' and an option '-CIPSO' can be used there :
593@ means Internet, any application with any label has access to it
594-CIPSO means standard CIPSO networking
595
596If you don't know what CIPSO is and don't plan to use it, you can just do :
Casey Schaufler18779b72015-03-31 09:49:40 -0700597echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
598echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
Etienne Basset43031542009-03-27 17:11:01 -0400599
600If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
601Internet access, you can have :
Casey Schaufler18779b72015-03-31 09:49:40 -0700602echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
603echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
604echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
Etienne Basset43031542009-03-27 17:11:01 -0400605
606
Casey Schauflere114e472008-02-04 22:29:50 -0800607Writing Applications for Smack
608
609There are three sorts of applications that will run on a Smack system. How an
610application interacts with Smack will determine what it will have to do to
611work properly under Smack.
612
613Smack Ignorant Applications
614
615By far the majority of applications have no reason whatever to care about the
616unique properties of Smack. Since invoking a program has no impact on the
617Smack label associated with the process the only concern likely to arise is
618whether the process has execute access to the program.
619
620Smack Relevant Applications
621
622Some programs can be improved by teaching them about Smack, but do not make
623any security decisions themselves. The utility ls(1) is one example of such a
624program.
625
626Smack Enforcing Applications
627
628These are special programs that not only know about Smack, but participate in
629the enforcement of system policy. In most cases these are the programs that
630set up user sessions. There are also network services that provide information
631to processes running with various labels.
632
633File System Interfaces
634
635Smack maintains labels on file system objects using extended attributes. The
636Smack label of a file, directory, or other file system object can be obtained
637using getxattr(2).
638
639 len = getxattr("/", "security.SMACK64", value, sizeof (value));
640
641will put the Smack label of the root directory into value. A privileged
642process can set the Smack label of a file system object with setxattr(2).
643
644 len = strlen("Rubble");
645 rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
646
647will set the Smack label of /foo to "Rubble" if the program has appropriate
648privilege.
649
650Socket Interfaces
651
652The socket attributes can be read using fgetxattr(2).
653
654A privileged process can set the Smack label of outgoing packets with
655fsetxattr(2).
656
657 len = strlen("Rubble");
658 rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
659
660will set the Smack label "Rubble" on packets going out from the socket if the
661program has appropriate privilege.
662
663 rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
664
665will set the Smack label "*" as the object label against which incoming
666packets will be checked if the program has appropriate privilege.
667
668Administration
669
670Smack supports some mount options:
671
672 smackfsdef=label: specifies the label to give files that lack
673 the Smack label extended attribute.
674
675 smackfsroot=label: specifies the label to assign the root of the
676 file system if it lacks the Smack extended attribute.
677
678 smackfshat=label: specifies a label that must have read access to
679 all labels set on the filesystem. Not yet enforced.
680
681 smackfsfloor=label: specifies a label to which all labels set on the
682 filesystem must have read access. Not yet enforced.
683
684These mount options apply to all file system types.
685
Etienne Bassetecfcc532009-04-08 20:40:06 +0200686Smack auditing
687
688If you want Smack auditing of security events, you need to set CONFIG_AUDIT
689in your kernel configuration.
690By default, all denied events will be audited. You can change this behavior by
Casey Schaufler18779b72015-03-31 09:49:40 -0700691writing a single character to the /sys/fs/smackfs/logging file :
Etienne Bassetecfcc532009-04-08 20:40:06 +02006920 : no logging
6931 : log denied (default)
6942 : log accepted
6953 : log denied & accepted
696
697Events are logged as 'key=value' pairs, for each event you at least will get
Masanari Iida40e47122012-03-04 23:16:11 +0900698the subject, the object, the rights requested, the action, the kernel function
Etienne Bassetecfcc532009-04-08 20:40:06 +0200699that triggered the event, plus other pairs depending on the type of event
700audited.
Casey Schaufler18779b72015-03-31 09:49:40 -0700701
702Bringup Mode
703
704Bringup mode provides logging features that can make application
705configuration and system bringup easier. Configure the kernel with
706CONFIG_SECURITY_SMACK_BRINGUP to enable these features. When bringup
707mode is enabled accesses that succeed due to rules marked with the "b"
708access mode will logged. When a new label is introduced for processes
709rules can be added aggressively, marked with the "b". The logging allows
710tracking of which rules actual get used for that label.
711
712Another feature of bringup mode is the "unconfined" option. Writing
713a label to /sys/fs/smackfs/unconfined makes subjects with that label
714able to access any object, and objects with that label accessible to
715all subjects. Any access that is granted because a label is unconfined
716is logged. This feature is dangerous, as files and directories may
717be created in places they couldn't if the policy were being enforced.