Commit | Line | Data |
---|---|---|
163f1511 MW |
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 | database of the authorized devices and prompts user 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 from Intel Falcon Ridge Thunderbolt controller there are 4 | |
24 | security levels available. The reason for these is the fact that the | |
25 | connected devices can be DMA masters and thus read contents of the host | |
26 | memory without CPU and OS knowing about it. There are ways to prevent | |
27 | this by setting up an IOMMU but it is not always available for various | |
28 | 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``. user then can do 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 ``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 | The current security level can be read from | |
56 | ``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is | |
57 | the Thunderbolt domain the host controller manages. There is typically | |
58 | one domain per Thunderbolt host controller. | |
59 | ||
60 | If the security level reads as ``user`` or ``secure`` the connected | |
61 | device must be authorized by the user before PCIe tunnels are created | |
62 | (e.g the PCIe device appears). | |
63 | ||
64 | Each Thunderbolt device plugged in will appear in sysfs under | |
65 | ``/sys/bus/thunderbolt/devices``. The device directory carries | |
66 | information that can be used to identify the particular device, | |
67 | including its name and UUID. | |
68 | ||
69 | Authorizing devices when security level is ``user`` or ``secure`` | |
70 | ----------------------------------------------------------------- | |
71 | When a device is plugged in it will appear in sysfs as follows:: | |
72 | ||
73 | /sys/bus/thunderbolt/devices/0-1/authorized - 0 | |
74 | /sys/bus/thunderbolt/devices/0-1/device - 0x8004 | |
75 | /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter | |
76 | /sys/bus/thunderbolt/devices/0-1/vendor - 0x1 | |
77 | /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc. | |
78 | /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff | |
79 | ||
80 | The ``authorized`` attribute reads 0 which means no PCIe tunnels are | |
81 | created yet. The user can authorize the device by simply:: | |
82 | ||
83 | # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized | |
84 | ||
85 | This will create the PCIe tunnels and the device is now connected. | |
86 | ||
87 | If the device supports secure connect, and the domain security level is | |
88 | set to ``secure``, it has an additional attribute ``key`` which can hold | |
89 | a random 32 byte value used for authorization and challenging the device in | |
90 | future connects:: | |
91 | ||
92 | /sys/bus/thunderbolt/devices/0-3/authorized - 0 | |
93 | /sys/bus/thunderbolt/devices/0-3/device - 0x305 | |
94 | /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box | |
95 | /sys/bus/thunderbolt/devices/0-3/key - | |
96 | /sys/bus/thunderbolt/devices/0-3/vendor - 0x41 | |
97 | /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron | |
98 | /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16 | |
99 | ||
100 | Notice the key is empty by default. | |
101 | ||
102 | If the user does not want to use secure connect it can just ``echo 1`` | |
103 | to the ``authorized`` attribute and the PCIe tunnels will be created in | |
104 | the same way than in ``user`` security level. | |
105 | ||
106 | If the user wants to use secure connect, the first time the device is | |
107 | plugged a key needs to be created and send to the device:: | |
108 | ||
109 | # key=$(openssl rand -hex 32) | |
110 | # echo $key > /sys/bus/thunderbolt/devices/0-3/key | |
111 | # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized | |
112 | ||
113 | Now the device is connected (PCIe tunnels are created) and in addition | |
114 | the key is stored on the device NVM. | |
115 | ||
116 | Next time the device is plugged in the user can verify (challenge) the | |
117 | device using the same key:: | |
118 | ||
119 | # echo $key > /sys/bus/thunderbolt/devices/0-3/key | |
120 | # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized | |
121 | ||
122 | If the challenge the device returns back matches the one we expect based | |
123 | on the key, the device is connected and the PCIe tunnels are created. | |
124 | However, if the challenge failed no tunnels are created and error is | |
125 | returned to the user. | |
126 | ||
127 | If the user still wants to connect the device it can either approve | |
128 | the device without a key or write new key and write 1 to the | |
129 | ``authorized`` file to get the new key stored on the device NVM. | |
130 | ||
131 | Upgrading NVM on Thunderbolt device or host | |
132 | ------------------------------------------- | |
133 | Since most of the functionality is handled in a firmware running on a | |
134 | host controller or a device, it is important that the firmware can be | |
135 | upgraded to the latest where possible bugs in it have been fixed. | |
136 | Typically OEMs provide this firmware from their support site. | |
137 | ||
138 | There is also a central site which has links where to download firmwares | |
139 | for some machines: | |
140 | ||
141 | `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_ | |
142 | ||
143 | Before you upgrade firmware on a device or host, please make sure it is | |
144 | the suitable. Failing to do that may render the device (or host) in a | |
145 | state where it cannot be used properly anymore without special tools! | |
146 | ||
147 | Host NVM upgrade on Apple Macs is not supported. | |
148 | ||
149 | Once the NVM image has been downloaded, you need to plug in a | |
150 | Thunderbolt device so that the host controller appears. It does not | |
151 | matter which device is connected (unless you are upgrading NVM on a | |
152 | device - then you need to connect that particular device). | |
153 | ||
154 | Note OEM-specific method to power the controller up ("force power") may | |
155 | be available for your system in which case there is no need to plug in a | |
156 | Thunderbolt device. | |
157 | ||
158 | After that we can write the firmware to the non-active parts of the NVM | |
159 | of the host or device. As an example here is how Intel NUC6i7KYK (Skull | |
160 | Canyon) Thunderbolt controller NVM is upgraded:: | |
161 | ||
162 | # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem | |
163 | ||
164 | Once the operation completes we can trigger NVM authentication and | |
165 | upgrade process as follows:: | |
166 | ||
167 | # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate | |
168 | ||
169 | If no errors are returned, the host controller shortly disappears. Once | |
170 | it comes back the driver notices it and initiates a full power cycle. | |
171 | After a while the host controller appears again and this time it should | |
172 | be fully functional. | |
173 | ||
174 | We can verify that the new NVM firmware is active by running following | |
175 | commands:: | |
176 | ||
177 | # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate | |
178 | 0x0 | |
179 | # cat /sys/bus/thunderbolt/devices/0-0/nvm_version | |
180 | 18.0 | |
181 | ||
182 | If ``nvm_authenticate`` contains anything else than 0x0 it is the error | |
183 | code from the last authentication cycle, which means the authentication | |
184 | of the NVM image failed. | |
185 | ||
186 | Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` | |
187 | depends on the order they are registered in the NVMem subsystem. N in | |
188 | the name is the identifier added by the NVMem subsystem. | |
189 | ||
190 | Upgrading NVM when host controller is in safe mode | |
191 | -------------------------------------------------- | |
192 | If the existing NVM is not properly authenticated (or is missing) the | |
193 | host controller goes into safe mode which means that only available | |
194 | functionality is flashing new NVM image. When in this mode the reading | |
195 | ``nvm_version`` fails with ``ENODATA`` and the device identification | |
196 | information is missing. | |
197 | ||
198 | To recover from this mode, one needs to flash a valid NVM image to the | |
199 | host host controller in the same way it is done in the previous chapter. |