Merge branch 'next-integrity' of git://git.kernel.org/pub/scm/linux/kernel/git/jmorri...
[sfrench/cifs-2.6.git] / Documentation / admin-guide / thunderbolt.rst
1 =============
2  Thunderbolt
3 =============
4 The interface presented here is not meant for end users. Instead there
5 should be a userspace tool that handles all the low-level details, keeps
6 a database of the authorized devices and prompts users for new connections.
7
8 More details about the sysfs interface for Thunderbolt devices can be
9 found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``.
10
11 Those users who just want to connect any device without any sort of
12 manual work can add following line to
13 ``/etc/udev/rules.d/99-local.rules``::
14
15   ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"
16
17 This will authorize all devices automatically when they appear. However,
18 keep in mind that this bypasses the security levels and makes the system
19 vulnerable to DMA attacks.
20
21 Security levels and how to use them
22 -----------------------------------
23 Starting with Intel Falcon Ridge Thunderbolt controller there are 4
24 security levels available. Intel Titan Ridge added one more security level
25 (usbonly). The reason for these is the fact that the connected devices can
26 be DMA masters and thus read contents of the host memory without CPU and OS
27 knowing about it. There are ways to prevent this by setting up an IOMMU but
28 it is not always available for various reasons.
29
30 The security levels are as follows:
31
32   none
33     All devices are automatically connected by the firmware. No user
34     approval is needed. In BIOS settings this is typically called
35     *Legacy mode*.
36
37   user
38     User is asked whether the device is allowed to be connected.
39     Based on the device identification information available through
40     ``/sys/bus/thunderbolt/devices``, the user then can make the decision.
41     In BIOS settings this is typically called *Unique ID*.
42
43   secure
44     User is asked whether the device is allowed to be connected. In
45     addition to UUID the device (if it supports secure connect) is sent
46     a challenge that should match the expected one based on a random key
47     written to the ``key`` sysfs attribute. In BIOS settings this is
48     typically called *One time saved key*.
49
50   dponly
51     The firmware automatically creates tunnels for Display Port and
52     USB. No PCIe tunneling is done. In BIOS settings this is
53     typically called *Display Port Only*.
54
55   usbonly
56     The firmware automatically creates tunnels for the USB controller and
57     Display Port in a dock. All PCIe links downstream of the dock are
58     removed.
59
60 The current security level can be read from
61 ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is
62 the Thunderbolt domain the host controller manages. There is typically
63 one domain per Thunderbolt host controller.
64
65 If the security level reads as ``user`` or ``secure`` the connected
66 device must be authorized by the user before PCIe tunnels are created
67 (e.g the PCIe device appears).
68
69 Each Thunderbolt device plugged in will appear in sysfs under
70 ``/sys/bus/thunderbolt/devices``. The device directory carries
71 information that can be used to identify the particular device,
72 including its name and UUID.
73
74 Authorizing devices when security level is ``user`` or ``secure``
75 -----------------------------------------------------------------
76 When a device is plugged in it will appear in sysfs as follows::
77
78   /sys/bus/thunderbolt/devices/0-1/authorized   - 0
79   /sys/bus/thunderbolt/devices/0-1/device       - 0x8004
80   /sys/bus/thunderbolt/devices/0-1/device_name  - Thunderbolt to FireWire Adapter
81   /sys/bus/thunderbolt/devices/0-1/vendor       - 0x1
82   /sys/bus/thunderbolt/devices/0-1/vendor_name  - Apple, Inc.
83   /sys/bus/thunderbolt/devices/0-1/unique_id    - e0376f00-0300-0100-ffff-ffffffffffff
84
85 The ``authorized`` attribute reads 0 which means no PCIe tunnels are
86 created yet. The user can authorize the device by simply entering::
87
88   # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized
89
90 This will create the PCIe tunnels and the device is now connected.
91
92 If the device supports secure connect, and the domain security level is
93 set to ``secure``, it has an additional attribute ``key`` which can hold
94 a random 32-byte value used for authorization and challenging the device in
95 future connects::
96
97   /sys/bus/thunderbolt/devices/0-3/authorized   - 0
98   /sys/bus/thunderbolt/devices/0-3/device       - 0x305
99   /sys/bus/thunderbolt/devices/0-3/device_name  - AKiTiO Thunder3 PCIe Box
100   /sys/bus/thunderbolt/devices/0-3/key          -
101   /sys/bus/thunderbolt/devices/0-3/vendor       - 0x41
102   /sys/bus/thunderbolt/devices/0-3/vendor_name  - inXtron
103   /sys/bus/thunderbolt/devices/0-3/unique_id    - dc010000-0000-8508-a22d-32ca6421cb16
104
105 Notice the key is empty by default.
106
107 If the user does not want to use secure connect they can just ``echo 1``
108 to the ``authorized`` attribute and the PCIe tunnels will be created in
109 the same way as in the ``user`` security level.
110
111 If the user wants to use secure connect, the first time the device is
112 plugged a key needs to be created and sent to the device::
113
114   # key=$(openssl rand -hex 32)
115   # echo $key > /sys/bus/thunderbolt/devices/0-3/key
116   # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized
117
118 Now the device is connected (PCIe tunnels are created) and in addition
119 the key is stored on the device NVM.
120
121 Next time the device is plugged in the user can verify (challenge) the
122 device using the same key::
123
124   # echo $key > /sys/bus/thunderbolt/devices/0-3/key
125   # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized
126
127 If the challenge the device returns back matches the one we expect based
128 on the key, the device is connected and the PCIe tunnels are created.
129 However, if the challenge fails no tunnels are created and error is
130 returned to the user.
131
132 If the user still wants to connect the device they can either approve
133 the device without a key or write a new key and write 1 to the
134 ``authorized`` file to get the new key stored on the device NVM.
135
136 DMA protection utilizing IOMMU
137 ------------------------------
138 Recent systems from 2018 and forward with Thunderbolt ports may natively
139 support IOMMU. This means that Thunderbolt security is handled by an IOMMU
140 so connected devices cannot access memory regions outside of what is
141 allocated for them by drivers. When Linux is running on such system it
142 automatically enables IOMMU if not enabled by the user already. These
143 systems can be identified by reading ``1`` from
144 ``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute.
145
146 The driver does not do anything special in this case but because DMA
147 protection is handled by the IOMMU, security levels (if set) are
148 redundant. For this reason some systems ship with security level set to
149 ``none``. Other systems have security level set to ``user`` in order to
150 support downgrade to older OS, so users who want to automatically
151 authorize devices when IOMMU DMA protection is enabled can use the
152 following ``udev`` rule::
153
154   ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1"
155
156 Upgrading NVM on Thunderbolt device or host
157 -------------------------------------------
158 Since most of the functionality is handled in firmware running on a
159 host controller or a device, it is important that the firmware can be
160 upgraded to the latest where possible bugs in it have been fixed.
161 Typically OEMs provide this firmware from their support site.
162
163 There is also a central site which has links where to download firmware
164 for some machines:
165
166   `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_
167
168 Before you upgrade firmware on a device or host, please make sure it is a
169 suitable upgrade. Failing to do that may render the device (or host) in a
170 state where it cannot be used properly anymore without special tools!
171
172 Host NVM upgrade on Apple Macs is not supported.
173
174 Once the NVM image has been downloaded, you need to plug in a
175 Thunderbolt device so that the host controller appears. It does not
176 matter which device is connected (unless you are upgrading NVM on a
177 device - then you need to connect that particular device).
178
179 Note an OEM-specific method to power the controller up ("force power") may
180 be available for your system in which case there is no need to plug in a
181 Thunderbolt device.
182
183 After that we can write the firmware to the non-active parts of the NVM
184 of the host or device. As an example here is how Intel NUC6i7KYK (Skull
185 Canyon) Thunderbolt controller NVM is upgraded::
186
187   # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem
188
189 Once the operation completes we can trigger NVM authentication and
190 upgrade process as follows::
191
192   # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
193
194 If no errors are returned, the host controller shortly disappears. Once
195 it comes back the driver notices it and initiates a full power cycle.
196 After a while the host controller appears again and this time it should
197 be fully functional.
198
199 We can verify that the new NVM firmware is active by running the following
200 commands::
201
202   # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
203   0x0
204   # cat /sys/bus/thunderbolt/devices/0-0/nvm_version
205   18.0
206
207 If ``nvm_authenticate`` contains anything other than 0x0 it is the error
208 code from the last authentication cycle, which means the authentication
209 of the NVM image failed.
210
211 Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN``
212 depend on the order they are registered in the NVMem subsystem. N in
213 the name is the identifier added by the NVMem subsystem.
214
215 Upgrading NVM when host controller is in safe mode
216 --------------------------------------------------
217 If the existing NVM is not properly authenticated (or is missing) the
218 host controller goes into safe mode which means that the only available
219 functionality is flashing a new NVM image. When in this mode, reading
220 ``nvm_version`` fails with ``ENODATA`` and the device identification
221 information is missing.
222
223 To recover from this mode, one needs to flash a valid NVM image to the
224 host controller in the same way it is done in the previous chapter.
225
226 Networking over Thunderbolt cable
227 ---------------------------------
228 Thunderbolt technology allows software communication between two hosts
229 connected by a Thunderbolt cable.
230
231 It is possible to tunnel any kind of traffic over a Thunderbolt link but
232 currently we only support Apple ThunderboltIP protocol.
233
234 If the other host is running Windows or macOS, the only thing you need to
235 do is to connect a Thunderbolt cable between the two hosts; the
236 ``thunderbolt-net`` driver is loaded automatically. If the other host is
237 also Linux you should load ``thunderbolt-net`` manually on one host (it
238 does not matter which one)::
239
240   # modprobe thunderbolt-net
241
242 This triggers module load on the other host automatically. If the driver
243 is built-in to the kernel image, there is no need to do anything.
244
245 The driver will create one virtual ethernet interface per Thunderbolt
246 port which are named like ``thunderbolt0`` and so on. From this point
247 you can either use standard userspace tools like ``ifconfig`` to
248 configure the interface or let your GUI handle it automatically.
249
250 Forcing power
251 -------------
252 Many OEMs include a method that can be used to force the power of a
253 Thunderbolt controller to an "On" state even if nothing is connected.
254 If supported by your machine this will be exposed by the WMI bus with
255 a sysfs attribute called "force_power".
256
257 For example the intel-wmi-thunderbolt driver exposes this attribute in:
258   /sys/bus/wmi/devices/86CCFD48-205E-4A77-9C48-2021CBEDE341/force_power
259
260   To force the power to on, write 1 to this attribute file.
261   To disable force power, write 0 to this attribute file.
262
263 Note: it's currently not possible to query the force power state of a platform.