<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html data-context="Build Apps" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<title>SMACK Security and Legato  - Legato Docs</title>
<meta content="legato™ is an open source Linux-based embedded platform designed to simplify connected IoT application development" name="description"/>
<meta content="legato, iot" name="keywords"/>
<meta content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" name="viewport"/>
<meta content="20.08.0" name="legato-version"/>
<link href="resources/images/legato.ico" rel="shortcut icon"/>
<link href="resources/images/legato.ico" rel="icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="apple-touch-icon" type="image/x-icon"/>
<link href="resources/css/style.css" media="screen" rel="stylesheet" type="text/css"/>
<link href="resources/css/font-awesome.css" rel="stylesheet" type="text/css"/>
<!--[if IE]>
    <script src="resources/js/html5shiv.js"></script>
    <script src="resources/js/respond.js"></script>
  <![endif]-->
<script src="https://code.jquery.com/jquery-2.2.3.min.js"></script>
<script src="resources/js/main.js"></script>
<script src="tocs/Build_Apps_Concepts.json"></script>
</head>
<body>
<noscript>
<input class="modal-closing-trick" id="modal-closing-trick" type="checkbox"/>
<div id="nojs">
<label for="modal-closing-trick">
<span>You seem to not have Javascript <a href="http://enable-javascript.com">enabled</a>, so site functionality like the search and navigation tree won't work.</span>
</label>
</div>
</noscript>
<div class="wrapper">
<div class="fa fa-bars documentation" id="menu-trigger"></div>
<div id="top">
<header>
<nav>
<a class="navlink" href="/">Introduction</a><a class="navlink selected" href="buildAppsMain.html">Build Apps</a><a class="navlink" href="buildPlatformMain.html">Build Platform</a><a class="navlink" href="aboutMain.html">About</a>
</nav>
</header>
</div>
<div class="white" id="menudocumentation">
<header>
<a href="/"> <img alt="Back to Legato Homepage" id="logo" src="resources/images/legato_logo.png"/></a>
<h2>/ Build Apps</h2>
<nav class="secondary">
<a href="getStarted.html">Get Started</a><a class="link-selected" href="concepts.html">Concepts</a><a href="apiGuidesMain.html">API Guides</a><a href="tools.html">Tools</a><a href="howToMain.html">How To</a><a href="experimentalMain.html">Experimental Features</a>
</nav>
<nav class="ui-front">
<i class="fa fa-search" id="search-icon"></i>
<input id="searchbox" placeholder="Search"/>
</nav>
</header>
</div>
<div id="resizable">
<div id="left">
<div id="tree1"></div>
</div>
</div>
<div class="content">
<div class="header">
<div class="headertitle">
<h1 class="title">SMACK Security and Legato </h1> </div>
</div><div class="contents">
<div class="textblock"><h1><a class="anchor" id="conceptsSecuritySmack_Overview"></a>
SMACK Overview</h1>
<p>SMACK <b>Simplified Mandatory Access Control Kernel</b> allows an administrator to define labels, for resources within a system. Labels on objects are compared with the labels of a task that tries to access them. By default, access is only allowed if the labels match. There are also a set of Smack-reserved labels that follow a different set of rules, which allows most system objects and processes to be unaffected by Smack restrictions. SMACK is designed to secure users and processes which is why it is enabled within the Legato system.</p>
<p>Within Linux files, devices, and other special objects within the filesystem are given permission bits that govern how processes may access these files.</p>
<p>For example, listing the root directory of the current active Legato system: </p><pre class="fragment">$ /legato/systems/current $ ll
drwxrwxr-x    2 root     root        1.9K Sep 27 01:07 apps
dr-x---r-x   19 root     root        1.4K Sep 27 01:07 appsWriteable
drwxrwxr-x    2 root     root        2.5K Sep 17 22:44 bin
drwxrwxr-x    2 root     root        2.1K Sep 27 01:07 config
-rw-r--r--    1 root     root           2 Sep 27 01:07 index
-rw-rw-rw-    1 root     root          37 Sep 27 01:07 info.properties
drwxrwxr-x    2 root     root        1.5K Sep 17 22:44 lib
-rw-r--r--    1 root     root           0 Sep 27 01:07 modified
drwxrwxr-x    3 root     root         296 Sep 17 22:44 modules
-rw-r--r--    1 root     root           4 Sep 27 01:07 status
-rw-r--r--    1 root     root          68 Sep 27 01:07 version
</pre><p>The first column of the output shows the permission bits for each file. See <a href="https://www.linux.com/learn/understanding-linux-file-permissions">this document</a> for more details on how the standard file permissions work in Linux.</p>
<p>File permissions are not enough security for all different potential usages of a production Linux system and security requirements can vary between contexts; the Linux Kernel team implemented a system of plugable security modules, one of which is SMACK.</p>
<p>SMACK is layered on top of the existing security module. When a file is opened for reading, writing, or execution the standard file permission bits are always checked first. If that check passes, then the SMACK security module is queried for access. It is then up to that security module to provide a final allow/deny for that object.</p>
<p>SMACK works by allowing one to apply to files, processes, devices, and resources like sockets a label. When a process tries to open a file, SMACK will read the label of the process requesting the access. The label of the file or object being accessed is then also read. SMACK will then compare those two labels. If the labels match, access is granted. If the labels are different then SMACK iterate over a list of rules. If a rule is found that matches both labels and the access requested then the access is granted. Otherwise the access is denied, and the error is passed back to the requesting process.</p>
<p>While SMACK itself runs entirely within the Linux kernel, there are associated user-space tools and devices that allow one to inspect and change labels as well as update the rules that bind these labels together.</p>
<h2><a class="anchor" id="conceptsSecuritySmack_Overview_Lables"></a>
SMACK Labels</h2>
<p>There are a number of labels built into SMACK, "_", "^", "*", "?", and "@".</p>
<p>Built in rules for these labels:</p>
<p><code>1</code>. All accesses by processes labelled "*" are denied. <code>2</code>. All read and execute requests, (no write,) for processes labelled, "^" are permitted. <code>3</code>. All read and execute requests, (no write,) on objects labelled, "_" are permitted, no matter what the process label. <code>4</code>. Any access requests, (read, write and execute,) on objects labelled, "*" no matter the process label are permitted. <code>5</code>. Any accesses on an object that has the same label as the process label are permitted. <code>6</code>. Any other accesses are denied, unless there is a user defined rule supplied at runtime.</p>
<p>SMACK labels on File System objects are stored as <a href="https://en.wikipedia.org/wiki/Extended_file_attributes#Linux">extended attributes</a>, (xattr.) These extended attributes are a generic way to store extra information to be associated with a file. The labels known to SMACK are:</p>
<ul>
<li><b>security.SMACK64:</b> The label for the file itself. If a file is being accessed then the access check is performed against the label stored in this attribute.</li>
<li><b>security.SMACK64EXEC:</b> When a process is started from a file, the label for the new process can be found in this attribute.</li>
<li><b>security.SMACK64IPIN:</b> If the object is a socket this label is used control incoming to the socket.</li>
<li><b>security.SMACK64IPOUT:</b> If the object is a socket this label is use to control access to the data being sent out from this device.</li>
</ul>
<h2><a class="anchor" id="conceptsSecuritySmack_getSetLabels"></a>
Getting and Setting Labels</h2>
<p>It is possible to read SMACK labels for filesystem (FS) objects. If your process has permission, you can also change labels on FS objects.</p>
<p>For files and sockets and other objects that are directly represented in the file system you can use the Linux tool <code>getfattr</code> to read a filesystem objects, "extended attributes."</p>
<p>For example I can run <code>getfattr</code> on my helloWorld app to see the following lables: </p><pre class="fragment"># getfattr -dm- helloWorld/
file: helloWorld/
security.SMACK64="framework"
</pre><p>It is in these extended attributes that SMACK stores the label(s) for an object. For regular files they can only have the one label attribute named "security.SMACK64". If the object is a socket it can have three labels, <code>security.SMACK64</code>, <code>security.SMACK64IPIN</code>, and <code>security.SMACK64IPOUT</code>.</p>
<p>In order to examine the labels of running processes you need to go to the process filesystem, under /proc.</p>
<p>For example, in order to display the label of the shell you are currently running in you can issue the following command:</p>
<pre class="fragment">cat /proc/$$/attr/current ; echo
</pre><p>Where the variable <code>$</code> in the previous line is automatically set by the shell to the PID of the shell's process. If you wish to examine the labels of other processes you need to know their PID. One trick is to use the Linux command <code>pidof</code>. You supply <code>pidof</code> the name of a process.</p>
<p>For example, to get the label of the configTree you would issue the command:</p>
<pre class="fragment">cat /proc/`pidof helloWorld`/attr/current ; echo
</pre><dl class="section note"><dt>Note</dt><dd>If there are multiple processes of the same name, <code>pidof</code> will return a list of PIDs and you may need some other way to determine the PID of the process you want.</dd></dl>
<p>If you're writing code to read the label of your own process you can use the <code>self</code> symlink without needing to know the PID for your process. Simply open the file <code>/proc/self/attr/current</code>.</p>
<p>You can also do this from the shell, but keep in mind, not all shell commands are built into the shell. Results may differ depending on how you structure your commands.</p>
<p>If for example you run: </p><pre class="fragment">cat /proc/self/attr/current ; echo
</pre><p>Instead of the previous: </p><pre class="fragment">cat /proc/$$/attr/current ; echo
</pre><p>You will end up with the label of the <code>cat</code> process and not the shell process.</p>
<h1><a class="anchor" id="conceptsSecuritySmack_Capabilities"></a>
SMACK Capabilities</h1>
<p>Processes can be given a set of <b>capabilities</b> and its the position of these capabilities that allow certain actions to be taken (i.e.; changing labels on files and processes or changing rules).</p>
<p>To modify labels and rules you must have the correct capabilities, by default in the Legato Linux system all process are run by the root user and automatically have this capability.</p>
<p>A good place to read more about SMACK and its configuration is to check out its <a href="https://www.kernel.org/doc/Documentation/security/Smack.txt">official documentation</a>.</p>
<h1><a class="anchor" id="conceptsSecuritySmack_onlycap"></a>
SMACK onlycap</h1>
<p>In standard operations, all processes run under the root user are given access to all SMACK labels and have all capabilities enabled. That is any process under root can do pretty much anything it wants with no trouble.</p>
<p>This can be a large security hole. If a process can escalate to running something under the root user, then that potentially malicious code can do anything it wants to the device.</p>
<p>To resolve this we've enabled SMACK onlycap. SMACK onlycap allows the system administrator to designate a single label with heightened privilege. Once this is in effect only the properly labeled processes may change labels and rules and all of the other SMACK rules are always in effect regardless of the user the process is running under.</p>
<p>The Legato makefile includes the option of turning onlycap support on. (Note that you need a Linux system image with the base support enabled.)</p>
<p>To build Legato with onlycap support enabled for the <code>wp76</code> run:</p>
<pre class="fragment">make menuconfig_wp76xx
</pre><p>Then, in the displayed configuration menu, enable SMACK onlycap (Framework &gt; Security Features &gt; Enable SMACK onlycap).</p>
<h1><a class="anchor" id="conceptsSecuritySmack_smackUsage"></a>
How SMACK is configured in Legato</h1>
<p>The Legato Supervisor and Update Daemon is given the label, "admin". Onlycap is enabled on this label, thus only the supervisor and update daemon will be able to adjust labels and rules. Other framework daemons (serviceDirectory, configTree etc.) are given the SMACK label "framework".</p>
<p>All applications run under their own labels of the form "app.&lt;app-name&gt;". All unsandboxed apps are given rules to give them access that give them read/write access to the system.</p>
<p>SMACK rules are set so IPC bindings between apps work. Here's a code sample of rules to set if a client app needs to access a server app:</p>
<p>On the target, set the rules in the <code>/legato/smack/load2</code> file. </p><pre class="fragment">'clientAppLabel' rw 'serverAppLabel'
'serverAppLabel' rw 'clientAppLabel'
</pre><p>Sandboxed directories are given labels corresponding to the app's access rights to those directory. Generally, an app only has read and execute permission to its sandboxes /bin directory.</p>
<p>Example properties: </p><pre class="fragment">owner = root
group = root
DAC permissions = ------r-x
SMACK label = 'AppLabelrx'
</pre><p>The Supervisor also sets up the SMACK rule so the app has the proper access to the directory:</p>
<p>On the target, set the rules in the <code>/legato/smack/load2</code> file. </p><pre class="fragment">'AppLabel' rx 'AppLabelrx'
</pre><p>App's directories are given different labels from the app itself so that if an IPC binding is present. The remote app has access to the local app but doesn't have direct access to the local app's files.</p>
<p>All bundled files within an app's sandbox are given the app's SMACK label. This supports passing file descriptors from one app to another. However, the file descriptor can't be passed onto a third app.</p>
<p>Legato also includes an assistance API to help with working with SMACK, see smack.h for more details.</p>
<h1><a class="anchor" id="conceptsSecuritySmack_limitations"></a>
Limitations</h1>
<p>Extended attributes used to store the SMACK label are available on all file systems we currently use with one key feature is missing: when a new file is created, the file should inherit the SMACK label of the creator. Because this feature is missing, our current implementation of SMACK has the following limitations:</p><ul>
<li>Mqueue file system will always set new files to "_" label. This means we can't control access between apps that use MQueues.</li>
<li>Tmpfs always sets new files to "*" label. This means we can't totally control access to files created in sandboxes because sandboxes use tmpfs. It's only an issue when file descriptors for the created files are passed over IPC to another app. The other app can then pass that fd onto a third app and so on.</li>
<li>QMI sockets are currently set to "*" because some apps need to write to them. Ideally, the QMI socket file would be given a label such as "qmi" and a rule would be created to only allow access to the app that requires it. However, there currently isn't a way to specify this in the xdef file.</li>
</ul>
<h1><a class="anchor" id="conceptsSecuritySmack_troubleshooting"></a>
Troubleshooting</h1>
<p>If you encounter problems with SMACK permissions while developing your apps you can enable <b>SMACK</b> <b>auditing</b>. To do this you need to change Kernel build flags and rebuild your Linux image.</p>
<p>In the Yocto wp76 source tree open the file:</p>
<pre class="fragment">kernel/arch/arm/configs/mdm9607_defconfig
</pre><p>Make sure that the following flags are set:</p>
<pre class="fragment">CONFIG_SECURITY_SMACK_BRINGUP=y
CONFIG_AUDIT=y
CONFIG_AUDITSYSCALL=y
</pre><p>Once done, save/rebuild/install the Linux image.</p>
<p>To enable logging for an app or label of your choice, write the label that's having troubles to the special device file unconfined, for example if your app is named, "myTestApp". You can run the command in your shell:</p>
<p>echo "app.myTestApp" &gt; /legato/smack/unconfined</p>
<p>This will bypass all SMACK rules for any accesses for this label, but if the rule would fail in normal operation the SMACK subsystem will now log the access request and the reason for the failure.</p>
<dl class="section note"><dt>Note</dt><dd>You can only install one label at a time.</dd></dl>
<p class="copyright">Copyright (C) Sierra Wireless Inc. </p>
</div></div>
<br clear="left"/>
</div>
</div>
<link href="resources/css/jqtree.css" rel="stylesheet" type="text/css"/>
<script src="resources/js/tree.jquery.js" type="text/javascript"></script>
<script src="resources/js/jquery.cookie.js"></script>
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
<link href="resources/css/perfect-scrollbar.min.css" rel="stylesheet"/>
<script src="resources/js/perfect-scrollbar.jquery.min.js"></script>
</body>
</html>
