<!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>Authorizing (or not) your USB devices to connect to the system — 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="ChipIdea Highspeed Dual Role Controller Driver" href="chipidea.html" />
<link rel="prev" title="Linux ACM driver v0.16" href="acm.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"><a class="reference internal" href="../security/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 current"><a class="reference internal" href="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/usb/authorization.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="authorizing-or-not-your-usb-devices-to-connect-to-the-system">
<h1>Authorizing (or not) your USB devices to connect to the system<a class="headerlink" href="#authorizing-or-not-your-usb-devices-to-connect-to-the-system" title="Link to this heading">¶</a></h1>
<p>Copyright (C) 2007 Inaky Perez-Gonzalez <<a class="reference external" href="mailto:inaky%40linux.intel.com">inaky<span>@</span>linux<span>.</span>intel<span>.</span>com</a>> Intel Corporation</p>
<p>This feature allows you to control if a USB device can be used (or
not) in a system. This feature will allow you to implement a lock-down
of USB devices, fully controlled by user space.</p>
<p>As of now, when a USB device is connected it is configured and
its interfaces are immediately made available to the users. With this
modification, only if root authorizes the device to be configured will
then it be possible to use it.</p>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<p>Authorize a device to connect:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized
</pre></div>
</div>
<p>De-authorize a device:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized
</pre></div>
</div>
<p>Set new devices connected to hostX to be deauthorized by default (ie:
lock down):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default
</pre></div>
</div>
<p>Remove the lock down:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default
</pre></div>
</div>
<p>By default, all USB devices are authorized. Writing “2” to the
authorized_default attribute causes the kernel to authorize by default
only devices connected to internal USB ports.</p>
<section id="example-system-lockdown-lame">
<h3>Example system lockdown (lame)<a class="headerlink" href="#example-system-lockdown-lame" title="Link to this heading">¶</a></h3>
<p>Imagine you want to implement a lockdown so only devices of type XYZ
can be connected (for example, it is a kiosk machine with a visible
USB port):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>boot up
rc.local ->
for host in /sys/bus/usb/devices/usb*
do
echo 0 > $host/authorized_default
done
</pre></div>
</div>
<p>Hookup an script to udev, for new USB devices:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>if device_is_my_type $DEV
then
echo 1 > $device_path/authorized
done
</pre></div>
</div>
<p>Now, <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">device_is_my_type()</span></code> is where the juice for a lockdown is. Just
checking if the class, type and protocol match something is the worse
security verification you can make (or the best, for someone willing
to break it). If you need something secure, use crypto and Certificate
Authentication or stuff like that. Something simple for an storage key
could be:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>function device_is_my_type()
{
echo 1 > authorized # temporarily authorize it
# FIXME: make sure none can mount it
mount DEVICENODE /mntpoint
sum=$(md5sum /mntpoint/.signature)
if [ $sum = $(cat /etc/lockdown/keysum) ]
then
echo "We are good, connected"
umount /mntpoint
# Other stuff so others can use it
else
echo 0 > authorized
fi
}
</pre></div>
</div>
<p>Of course, this is lame, you’d want to do a real certificate
verification stuff with PKI, so you don’t depend on a shared secret,
etc, but you get the idea. Anybody with access to a device gadget kit
can fake descriptors and device info. Don’t trust that. You are
welcome.</p>
</section>
<section id="interface-authorization">
<h3>Interface authorization<a class="headerlink" href="#interface-authorization" title="Link to this heading">¶</a></h3>
<p>There is a similar approach to allow or deny specific USB interfaces.
That allows to block only a subset of an USB device.</p>
<p>Authorize an interface:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized
</pre></div>
</div>
<p>Deauthorize an interface:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized
</pre></div>
</div>
<p>The default value for new interfaces
on a particular USB bus can be changed, too.</p>
<p>Allow interfaces per default:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default
</pre></div>
</div>
<p>Deny interfaces per default:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default
</pre></div>
</div>
<p>Per default the interface_authorized_default bit is 1.
So all interfaces would authorized per default.</p>
<dl class="simple">
<dt>Note:</dt><dd><p>If a deauthorized interface will be authorized so the driver probing must
be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe</p>
</dd>
</dl>
<p>For drivers that need multiple interfaces all needed interfaces should be
authorized first. After that the drivers should be probed.
This avoids side effects.</p>
</section>
</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/usb/authorization.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>