README.md 2.5 KB
Newer Older
1 2 3
bolt
====

4
Userspace system daemon to enable security levels for *Thunderbolt™ 3*
5
on GNU/Linux®.
6 7 8 9 10

Introduction
------------

Thunderbolt™ is the brand name of a hardware interface developed by
11
Intel® that allows the connection of external peripherals to a
12 13 14 15
computer.

Devices connected via Thunderbolt can be DMA masters and thus read
system memory without interference of the operating system (or even
16
the CPU).  Version 3 of the interface provides 5 different security
17 18 19 20
levels, in order to mitigate the aforementioned security risk that
connected devices pose to the system. The security level is set by the
system firmware.

21 22 23 24 25 26 27 28 29 30 31 32 33
The five security levels are:

 * `none`:    Security disabled, all devices will fully functional
              on connect.
 * `dponly`:  Only pass the display-port stream through to the
              connected device.
 * `user`:    Connected devices need to be manually authorized by
              the user.
 * `secure`:  As 'user', but also challenge the device with a secret
              key to verify its identity.
 * `usbonly`: One PCIe tunnel is created to a usb controller in a
              thunderbolt dock; no other downstream PCIe tunnels are
              authorized (needs 4.17 kernel and recent hardware).
34

35
The Linux kernel, starting with version 4.13, provides an interface via
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
sysfs that enables userspace query the security level, the status of
connected devices and, most importantly, to authorize devices, if the
security level demands it.

boltd - the system daemon
-------------------------

The core of bolt is a system daemon (`boltd`) that interfaces with
sysfs and exposes devices via D-Bus to clients. It also has a database
of previously authorized devices (and their keys) and will, depending
on the policy set for the individual devices, automatically authorize
newly connected devices without user interaction.

boltctl - command line client
-----------------------------
The `boltctl` command line can be used to manage thunderbolt devices
via `boltd`.  It can list devices, monitor changes and initiate
53
authorization of devices.
54 55 56 57 58 59 60 61 62 63 64 65


Installation
============

The [meson][meson] build system is used to configure and compile bolt.


    meson build           # configure bolt, use build as buildir
    ninja -C build        # compile it
    ninja -C build test   # run the tests

Felix Yan's avatar
Felix Yan committed
66
See [INSTALL][install] for more information, [BUGS][bugs] for how to
67 68 69 70 71 72 73
file issues and [HACKING][hacking] how to contribute.


[meson]: http://mesonbuild.com/
[install]: INSTALL.md
[bugs]: BUGS.md
[hacking]: HACKING.md