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