<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Landlock LSM: kernel documentation — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Secrets documentation" href="secrets/index.html" />
<link rel="prev" title="Digital Signature Verification API" href="digsig.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../accounting/index.html">Accounting</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cpu-freq/index.html">CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel</a></li>
<li class="toctree-l3"><a class="reference internal" href="../edac/index.html">EDAC Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../fpga/index.html">FPGA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../i2c/index.html">I2C/SMBus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../iio/index.html">Industrial I/O</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pcmcia/index.html">PCMCIA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../spi/index.html">Serial Peripheral Interface (SPI)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../w1/index.html">1-Wire Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../watchdog/index.html">Watchdog Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../virt/index.html">Virtualization Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hwmon/index.html">Hardware Monitoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="../accel/index.html">Compute Accelerators</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Security Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../crypto/index.html">Crypto API</a></li>
<li class="toctree-l3"><a class="reference internal" href="../bpf/index.html">BPF Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../usb/index.html">USB support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../PCI/index.html">PCI Bus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../misc-devices/index.html">Assorted Miscellaneous Devices Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../peci/index.html">PECI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../wmi/index.html">WMI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../tee/index.html">TEE Subsystem</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/security/landlock.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="language-selection">
English
<ul>
<li><a href="../translations/zh_CN/security/landlock.html">Chinese (Simplified)</a></li>
</ul>
</div>
<section id="landlock-lsm-kernel-documentation">
<h1>Landlock LSM: kernel documentation<a class="headerlink" href="#landlock-lsm-kernel-documentation" title="Link to this heading">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Mickaël Salaün</p>
</dd>
<dt class="field-even">Date<span class="colon">:</span></dt>
<dd class="field-even"><p>March 2025</p>
</dd>
</dl>
<p>Landlock’s goal is to create scoped access-control (i.e. sandboxing). To
harden a whole system, this feature should be available to any process,
including unprivileged ones. Because such a process may be compromised or
backdoored (i.e. untrusted), Landlock’s features must be safe to use from the
kernel and other processes point of view. Landlock’s interface must therefore
expose a minimal attack surface.</p>
<p>Landlock is designed to be usable by unprivileged processes while following the
system security policy enforced by other access control mechanisms (e.g. DAC,
LSM). A Landlock rule shall not interfere with other access-controls enforced
on the system, only add more restrictions.</p>
<p>Any user can enforce Landlock rulesets on their processes. They are merged and
evaluated against inherited rulesets in a way that ensures that only more
constraints can be added.</p>
<p>User space documentation can be found here:
<a class="reference internal" href="../userspace-api/landlock.html"><span class="doc">Landlock: unprivileged access control</span></a>.</p>
<section id="guiding-principles-for-safe-access-controls">
<h2>Guiding principles for safe access controls<a class="headerlink" href="#guiding-principles-for-safe-access-controls" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p>A Landlock rule shall be focused on access control on kernel objects instead
of syscall filtering (i.e. syscall arguments), which is the purpose of
seccomp-bpf.</p></li>
<li><p>To avoid multiple kinds of side-channel attacks (e.g. leak of security
policies, CPU-based attacks), Landlock rules shall not be able to
programmatically communicate with user space.</p></li>
<li><p>Kernel access check shall not slow down access request from unsandboxed
processes.</p></li>
<li><p>Computation related to Landlock operations (e.g. enforcing a ruleset) shall
only impact the processes requesting them.</p></li>
<li><p>Resources (e.g. file descriptors) directly obtained from the kernel by a
sandboxed process shall retain their scoped accesses (at the time of resource
acquisition) whatever process uses them.
Cf. <a class="reference internal" href="#file-descriptor-access-rights">File descriptor access rights</a>.</p></li>
<li><p>Access denials shall be logged according to system and Landlock domain
configurations. Log entries must contain information about the cause of the
denial and the owner of the related security policy. Such log generation
should have a negligible performance and memory impact on allowed requests.</p></li>
</ul>
</section>
<section id="design-choices">
<h2>Design choices<a class="headerlink" href="#design-choices" title="Link to this heading">¶</a></h2>
<section id="inode-access-rights">
<h3>Inode access rights<a class="headerlink" href="#inode-access-rights" title="Link to this heading">¶</a></h3>
<p>All access rights are tied to an inode and what can be accessed through it.
Reading the content of a directory does not imply to be allowed to read the
content of a listed inode. Indeed, a file name is local to its parent
directory, and an inode can be referenced by multiple file names thanks to
(hard) links. Being able to unlink a file only has a direct impact on the
directory, not the unlinked inode. This is the reason why
<code class="docutils literal notranslate"><span class="pre">LANDLOCK_ACCESS_FS_REMOVE_FILE</span></code> or <code class="docutils literal notranslate"><span class="pre">LANDLOCK_ACCESS_FS_REFER</span></code> are not
allowed to be tied to files but only to directories.</p>
</section>
<section id="file-descriptor-access-rights">
<h3>File descriptor access rights<a class="headerlink" href="#file-descriptor-access-rights" title="Link to this heading">¶</a></h3>
<p>Access rights are checked and tied to file descriptors at open time. The
underlying principle is that equivalent sequences of operations should lead to
the same results, when they are executed under the same Landlock domain.</p>
<p>Taking the <code class="docutils literal notranslate"><span class="pre">LANDLOCK_ACCESS_FS_TRUNCATE</span></code> right as an example, it may be
allowed to open a file for writing without being allowed to
<em class="manpage">ftruncate</em> the resulting file descriptor if the related file
hierarchy doesn’t grant that access right. The following sequences of
operations have the same semantic and should then have the same result:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">truncate(path);</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">fd</span> <span class="pre">=</span> <span class="pre">open(path,</span> <span class="pre">O_WRONLY);</span> <span class="pre">ftruncate(fd);</span> <span class="pre">close(fd);</span></code></p></li>
</ul>
<p>Similarly to file access modes (e.g. <code class="docutils literal notranslate"><span class="pre">O_RDWR</span></code>), Landlock access rights
attached to file descriptors are retained even if they are passed between
processes (e.g. through a Unix domain socket). Such access rights will then be
enforced even if the receiving process is not sandboxed by Landlock. Indeed,
this is required to keep access controls consistent over the whole system, and
this avoids unattended bypasses through file descriptor passing (i.e. confused
deputy attack).</p>
</section>
</section>
<section id="tests">
<h2>Tests<a class="headerlink" href="#tests" title="Link to this heading">¶</a></h2>
<p>Userspace tests for backward compatibility, ptrace restrictions and filesystem
support can be found here: <a class="reference external" href="https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/">tools/testing/selftests/landlock/</a>.</p>
</section>
<section id="kernel-structures">
<h2>Kernel structures<a class="headerlink" href="#kernel-structures" title="Link to this heading">¶</a></h2>
<section id="object">
<h3>Object<a class="headerlink" href="#object" title="Link to this heading">¶</a></h3>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_object_underops">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_object_underops</span></span></span><a class="headerlink" href="#c.landlock_object_underops" title="Link to this definition">¶</a><br /></dt>
<dd><p>Operations on an underlying object</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_object_underops {
void (*release)(struct landlock_object *const object) __releases(object->lock);
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">release</span></code></dt><dd><p>Releases the underlying object (e.g. <a class="reference internal" href="../filesystems/api-summary.html#c.iput" title="iput"><code class="xref c c-func docutils literal notranslate"><span class="pre">iput()</span></code></a> for an inode).</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_object">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_object</span></span></span><a class="headerlink" href="#c.landlock_object" title="Link to this definition">¶</a><br /></dt>
<dd><p>Security blob tied to a kernel object</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_object {
refcount_t usage;
spinlock_t lock;
void *underobj;
union {
struct rcu_head rcu_free;
const struct landlock_object_underops *underops;
};
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">usage</span></code></dt><dd><p>This counter is used to tie an object to the rules matching
it or to keep it alive while adding a new rule. If this counter
reaches zero, this <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">must</span></code> not be modified, but this counter can
still be read from within an RCU read-side critical section. When
adding a new rule to an object with a usage counter of zero, we must
wait until the pointer to this object is set to NULL (or recycled).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">lock</span></code></dt><dd><p>Protects against concurrent modifications. This lock must be
held from the time <strong>usage</strong> drops to zero until any weak references
from <strong>underobj</strong> to this object have been cleaned up.</p>
<p>Lock ordering: inode->i_lock nests inside this.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">underobj</span></code></dt><dd><p>Used when cleaning up an object and to mark an object as
tied to its underlying kernel structure. This pointer is protected
by <strong>lock</strong>. Cf. <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">landlock_release_inodes()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">release_inode()</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">{unnamed_union}</span></code></dt><dd><p>anonymous</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">rcu_free</span></code></dt><dd><p>Enables lockless use of <strong>usage</strong>, <strong>lock</strong> and
<strong>underobj</strong> from within an RCU read-side critical section.
<strong>rcu_free</strong> and <strong>underops</strong> are only used by
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">landlock_put_object()</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">underops</span></code></dt><dd><p>Enables <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">landlock_put_object()</span></code> to release the
underlying object (e.g. inode).</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>The goal of this structure is to enable to tie a set of ephemeral access
rights (pertaining to different domains) to a kernel object (e.g an inode)
in a safe way. This implies to handle concurrent use and modification.</p>
<p>The lifetime of a <a class="reference internal" href="#c.landlock_object" title="landlock_object"><code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">landlock_object</span></code></a> depends on the rules referring to
it.</p>
</section>
<section id="filesystem">
<h3>Filesystem<a class="headerlink" href="#filesystem" title="Link to this heading">¶</a></h3>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_inode_security">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_inode_security</span></span></span><a class="headerlink" href="#c.landlock_inode_security" title="Link to this definition">¶</a><br /></dt>
<dd><p>Inode security blob</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_inode_security {
struct landlock_object __rcu *object;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">object</span></code></dt><dd><p>Weak pointer to an allocated object. All assignments of a
new object are protected by the underlying inode->i_lock. However,
atomically disassociating <strong>object</strong> from the inode is only protected
by <strong>object->lock</strong>, from the time <strong>object</strong>’s usage refcount drops to
zero to the time this pointer is nulled out (cf. <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">release_inode()</span></code> and
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">hook_sb_delete()</span></code>). Indeed, such disassociation doesn’t require
inode->i_lock thanks to the careful <a class="reference internal" href="../core-api/kernel-api.html#c.rcu_access_pointer" title="rcu_access_pointer"><code class="xref c c-func docutils literal notranslate"><span class="pre">rcu_access_pointer()</span></code></a> check
performed by <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">get_inode_object()</span></code>.</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>Enable to reference a <a class="reference internal" href="#c.landlock_object" title="landlock_object"><code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">landlock_object</span></code></a> tied to an inode (i.e.
underlying object).</p>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_file_security">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_file_security</span></span></span><a class="headerlink" href="#c.landlock_file_security" title="Link to this definition">¶</a><br /></dt>
<dd><p>File security blob</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_file_security {
access_mask_t allowed_access;
#ifdef CONFIG_AUDIT;
deny_masks_t deny_masks;
u8 fown_layer;
#endif;
struct landlock_cred_security fown_subject;
struct pid *fown_tg;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">allowed_access</span></code></dt><dd><p>Access rights that were available at the time of
opening the file. This is not necessarily the full set of access
rights available at that time, but it’s the necessary subset as
needed to authorize later operations on the open file.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">deny_masks</span></code></dt><dd><p>Domain layer levels that deny an optional access (see
_LANDLOCK_ACCESS_FS_OPTIONAL).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fown_layer</span></code></dt><dd><p>Layer level of <strong>fown_subject->domain</strong> with
LANDLOCK_SCOPE_SIGNAL.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fown_subject</span></code></dt><dd><p>Landlock credential of the task that set the PID that
may receive a signal e.g., SIGURG when writing MSG_OOB to the
related socket. This pointer is protected by the related
file->f_owner->lock, as for fown_struct’s members: pid, uid, and
euid.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fown_tg</span></code></dt><dd><p>Thread group of the task that set the file owner, pinned
while <strong>fown_subject</strong> holds a domain. It lets
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">hook_file_send_sigiotask()</span></code> always allow a SIGIO delivered to the
owner’s own process -- e.g. the thread-group leader reached through a
process-group owner -- matching the same-process exemption of
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">hook_task_kill()</span></code>. NULL when no domain is recorded. Protected by
file->f_owner->lock, like <strong>fown_subject</strong>.</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>This information is populated when opening a file in hook_file_open, and
tracks the relevant Landlock access rights that were available at the time
of opening the file. Other LSM hooks use these rights in order to authorize
operations on already opened files.</p>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_superblock_security">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_superblock_security</span></span></span><a class="headerlink" href="#c.landlock_superblock_security" title="Link to this definition">¶</a><br /></dt>
<dd><p>Superblock security blob</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_superblock_security {
atomic_long_t inode_refs;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">inode_refs</span></code></dt><dd><p>Number of pending inodes (from this superblock) that
are being released by <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">release_inode()</span></code>.
Cf. <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">super_block</span></code>->s_fsnotify_inode_refs .</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>Enable <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">hook_sb_delete()</span></code> to wait for concurrent calls to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">release_inode()</span></code>.</p>
</section>
<section id="ruleset-and-domain">
<h3>Ruleset and domain<a class="headerlink" href="#ruleset-and-domain" title="Link to this heading">¶</a></h3>
<p>A domain is a read-only ruleset tied to a set of subjects (i.e. tasks’
credentials). Each time a ruleset is enforced on a task, the current domain is
duplicated and the ruleset is imported as a new layer of rules in the new
domain. Indeed, once in a domain, each rule is tied to a layer level. To
grant access to an object, at least one rule of each layer must allow the
requested action on the object. A task can then only transit to a new domain
that is the intersection of the constraints from the current domain and those
of a ruleset provided by the task.</p>
<p>The definition of a subject is implicit for a task sandboxing itself, which
makes the reasoning much easier and helps avoid pitfalls.</p>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_layer">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_layer</span></span></span><a class="headerlink" href="#c.landlock_layer" title="Link to this definition">¶</a><br /></dt>
<dd><p>Access rights for a given layer</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_layer {
u16 level;
access_mask_t access;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">level</span></code></dt><dd><p>Position of this layer in the layer stack.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">access</span></code></dt><dd><p>Bitfield of allowed actions on the kernel object. They are
relative to the object type (e.g. <code class="docutils literal notranslate"><span class="pre">LANDLOCK_ACTION_FS_READ</span></code>).</p>
</dd>
</dl>
</div>
<dl class="c union">
<dt class="sig sig-object c" id="c.landlock_key">
<span class="k"><span class="pre">union</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_key</span></span></span><a class="headerlink" href="#c.landlock_key" title="Link to this definition">¶</a><br /></dt>
<dd><p>Key of a ruleset’s red-black tree</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>union landlock_key {
struct landlock_object *object;
uintptr_t data;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">object</span></code></dt><dd><p>Pointer to identify a kernel object (e.g. an inode).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">data</span></code></dt><dd><p>Raw data to identify an arbitrary 32-bit value
(e.g. a TCP port).</p>
</dd>
</dl>
</div>
<dl class="c enum">
<dt class="sig sig-object c" id="c.landlock_key_type">
<span class="k"><span class="pre">enum</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_key_type</span></span></span><a class="headerlink" href="#c.landlock_key_type" title="Link to this definition">¶</a><br /></dt>
<dd><p>Type of <a class="reference internal" href="#c.landlock_key" title="landlock_key"><code class="xref c c-type docutils literal notranslate"><span class="pre">union</span> <span class="pre">landlock_key</span></code></a></p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Constants</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">LANDLOCK_KEY_INODE</span></code></dt><dd><p>Type of <a class="reference internal" href="#c.landlock_ruleset" title="landlock_ruleset"><code class="xref c c-type docutils literal notranslate"><span class="pre">landlock_ruleset.root_inode</span></code></a>’s node
keys.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">LANDLOCK_KEY_NET_PORT</span></code></dt><dd><p>Type of <a class="reference internal" href="#c.landlock_ruleset" title="landlock_ruleset"><code class="xref c c-type docutils literal notranslate"><span class="pre">landlock_ruleset.root_net_port</span></code></a>’s
node keys.</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_id">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_id</span></span></span><a class="headerlink" href="#c.landlock_id" title="Link to this definition">¶</a><br /></dt>
<dd><p>Unique rule identifier for a ruleset</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_id {
union landlock_key key;
const enum landlock_key_type type;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifies either a kernel object (e.g. an inode) or
a raw value (e.g. a TCP port).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">type</span></code></dt><dd><p>Type of a landlock_ruleset’s root tree.</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_rule">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_rule</span></span></span><a class="headerlink" href="#c.landlock_rule" title="Link to this definition">¶</a><br /></dt>
<dd><p>Access rights tied to an object</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_rule {
struct rb_node node;
union landlock_key key;
u32 num_layers;
struct landlock_layer layers[] ;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">node</span></code></dt><dd><p>Node in the ruleset’s red-black tree.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>A <code class="xref c c-union broken_xref docutils literal notranslate"><span class="pre">union</span> <span class="pre">to</span></code> identify either a kernel object (e.g. an inode) or
a raw data value (e.g. a network socket port). This is used as a key
for this ruleset element. The pointer is set once and never
modified. It always points to an allocated object because each rule
increments the refcount of its object.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">num_layers</span></code></dt><dd><p>Number of entries in <strong>layers</strong>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">layers</span></code></dt><dd><p>Stack of layers, from the latest to the newest, implemented
as a flexible array member (FAM).</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.landlock_ruleset">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_ruleset</span></span></span><a class="headerlink" href="#c.landlock_ruleset" title="Link to this definition">¶</a><br /></dt>
<dd><p>Landlock ruleset</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct landlock_ruleset {
struct rb_root root_inode;
#if IS_ENABLED(CONFIG_INET);
struct rb_root root_net_port;
#endif;
struct landlock_hierarchy *hierarchy;
union {
struct work_struct work_free;
struct {
struct mutex lock;
refcount_t usage;
u32 num_rules;
u32 num_layers;
struct access_masks access_masks[];
};
};
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">root_inode</span></code></dt><dd><p>Root of a red-black tree containing <a class="reference internal" href="#c.landlock_rule" title="landlock_rule"><code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">landlock_rule</span></code></a> nodes with inode object. Once a ruleset is tied to a
process (i.e. as a domain), this tree is immutable until <strong>usage</strong>
reaches zero.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">root_net_port</span></code></dt><dd><p>Root of a red-black tree containing <a class="reference internal" href="#c.landlock_rule" title="landlock_rule"><code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">landlock_rule</span></code></a> nodes with network port. Once a ruleset is tied to a
process (i.e. as a domain), this tree is immutable until <strong>usage</strong>
reaches zero.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">hierarchy</span></code></dt><dd><p>Enables hierarchy identification even when a parent
domain vanishes. This is needed for the ptrace protection.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">{unnamed_union}</span></code></dt><dd><p>anonymous</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">work_free</span></code></dt><dd><p>Enables to free a ruleset within a lockless
section. This is only used by
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">landlock_put_ruleset_deferred()</span></code> when <strong>usage</strong> reaches zero.
The fields <strong>lock</strong>, <strong>usage</strong>, <strong>num_rules</strong>, <strong>num_layers</strong> and
<strong>access_masks</strong> are then unused.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">{unnamed_struct}</span></code></dt><dd><p>anonymous</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">lock</span></code></dt><dd><p>Protects against concurrent modifications of
<strong>root</strong>, if <strong>usage</strong> is greater than zero.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">usage</span></code></dt><dd><p>Number of processes (i.e. domains) or file
descriptors referencing this ruleset.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">num_rules</span></code></dt><dd><p>Number of non-overlapping (i.e. not for
the same object) rules in this ruleset.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">num_layers</span></code></dt><dd><p>Number of layers that are used in this
ruleset. This enables to check that all the layers
allow an access request. A value of 0 identifies a
non-merged ruleset (i.e. not a domain).</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">access_masks</span></code></dt><dd><p>Contains the subset of filesystem and
network actions that are restricted by a ruleset.
A domain saves all layers of merged rulesets in a
stack (FAM), starting from the first layer to the
last one. These layers are used when merging
rulesets, for user space backward compatibility
(i.e. future-proof), and to properly handle merged
rulesets without overlapping access rights. These
layers are set once and never changed for the
lifetime of the ruleset.</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>This data structure must contain unique entries, be updatable, and quick to
match an object.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.landlock_union_access_masks">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">access_masks</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">landlock_union_access_masks</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.landlock_ruleset" title="landlock_ruleset"><span class="n"><span class="pre">landlock_ruleset</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">domain</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.landlock_union_access_masks" title="Link to this definition">¶</a><br /></dt>
<dd><p>Return all access rights handled in the domain</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">struct</span> <span class="pre">landlock_ruleset</span> <span class="pre">*const</span> <span class="pre">domain</span></code></dt><dd><p>Landlock ruleset (used as a domain)</p>
</dd>
</dl>
<p><strong>Return</strong></p>
<p>an access_masks result of the OR of all the domain’s access masks.</p>
</div>
</section>
</section>
<section id="additional-documentation">
<h2>Additional documentation<a class="headerlink" href="#additional-documentation" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="../userspace-api/landlock.html"><span class="doc">Landlock: unprivileged access control</span></a></p></li>
<li><p><a class="reference internal" href="../admin-guide/LSM/landlock.html"><span class="doc">Landlock: system-wide management</span></a></p></li>
<li><p><a class="reference external" href="https://landlock.io">https://landlock.io</a></p></li>
</ul>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/security/landlock.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>