mirror of
https://git.proxmox.com/git/fwupd
synced 2025-05-23 11:35:18 +00:00
172 lines
6.7 KiB
HTML
172 lines
6.7 KiB
HTML
<!DOCTYPE html>
|
|
<!-- Copyright (C) 2015 Richard Hughes <richard@hughsie.com>
|
|
Licensed under the GNU General Public License Version 2 -->
|
|
<html>
|
|
|
|
<head>
|
|
<title>fwupd: Firmware Update Daemon</title>
|
|
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
|
|
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,300' rel='stylesheet' type='text/css'>
|
|
<link rel="stylesheet" href="style.css" type="text/css" media="screen"/>
|
|
<link rel="shortcut icon" href="favicon.ico"/>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1 class="banner">fwupd: Firmware<br> Update Daemon</h1>
|
|
|
|
<h1>Introduction</h1>
|
|
<p>
|
|
A lot of people don't have UEFI hardware that is capable of applying capsule
|
|
firmware updates, so I've also added a ColorHug provider, which predictably also
|
|
lets you update the firmware on your <a href="http://www.hughski.com/">ColorHug</a> devices.
|
|
</p>
|
|
<p>
|
|
I'm also happy to accept patches for other hardware that supports updates.
|
|
The provider concept allows vendors to do pretty much anything to get the list
|
|
of attached hardware, as long as a unique hardware component is in some way
|
|
mapped to a GUID value.
|
|
Ideally the tools would be open source, or better still not needing any external
|
|
tools at all.
|
|
Reading a VID/PID and then writing firmware to a chip usually isn't rocket science.
|
|
</p>
|
|
<p>
|
|
<a href="http://www.freedesktop.org/software/appstream/docs/">AppStream 0.9</a>
|
|
is used as the interchange format for update descriptions.
|
|
A lot of tools already talk AppStream and so this makes working with
|
|
other desktop and server tools very easy. Actually generating the AppStream
|
|
metadata can either be done using using <code>appstream-builder</code> or the
|
|
<a href="vendors.html">Linux Vendor Firmware Service</a>.
|
|
</p>
|
|
|
|
<h1>Architecture</h1>
|
|
<p>
|
|
fwupd is implemented as a D-Bus activated service that is autostarted when
|
|
required.
|
|
</p>
|
|
<img src="img/architecture-plan.png" alt="architecture-plan"/>
|
|
<p>
|
|
The 'client' which is typically <code>gnome-software</code> or <code>fwupd</code>
|
|
does all the query, download and schedule steps.
|
|
This means that the daemon has no network access and only acts as the mechanism
|
|
for clients.
|
|
</p>
|
|
|
|
<h2>Getting the code</h2>
|
|
<p>
|
|
The latest code is always available at <a href="https://github.com/hughsie/fwupd">GitHub</a>
|
|
and this is also the place to file <a href="https://github.com/hughsie/fwupd/issues">bugs or feature requests</a>.
|
|
You can trivially get the code by doing:
|
|
</p>
|
|
<pre>
|
|
$ git clone https://github.com/hughsie/fwupd.git
|
|
</pre>
|
|
<p>
|
|
You can also install all the required dependancies using:
|
|
</p>
|
|
<pre>
|
|
$ sudo dnf install docbook-utils gettext intltool libgudev1-devel \
|
|
colord-devel polkit-devel libgcab1-devel \
|
|
sqlite-devel gpgme-devel fwupdate-devel libsoup-devel
|
|
</pre>
|
|
|
|
<h2>How does fwupd know the device firmware version?</h2>
|
|
<p>
|
|
There are currently several ways to detect the firmware version:
|
|
</p>
|
|
<ul>
|
|
<li>USB firmware version extensions (see below)</li>
|
|
<li>The <code>bcdVersion</code> for some USB devices</li>
|
|
<li>Parsing the option ROM and searching for serial numbers</li>
|
|
<li>Using <code>libfwupdate</code> to get the ESRT table data</li>
|
|
<li>Using a custom provider (not covered here)</li>
|
|
</ul>
|
|
|
|
<h3>USB Firmware Version Extensions</h3>
|
|
<p>
|
|
For generic USB devices you can use a firmware vendor extensions that are used
|
|
by several OpenHardware projects.
|
|
This means the fwupd daemon can obtain the GUID and firmware version without
|
|
claiming the interface on the device and preventing other software from using it.
|
|
</p>
|
|
<p>
|
|
To implement the firmware version extension just create an interface descriptor
|
|
with class code <code>0xff</code>, subclass code <code>0x46</code> and
|
|
protocol <code>0x57</code> pointing to a string descriptor with the firmware version.
|
|
An example commit to the ColorHug project can be found
|
|
<a href="https://github.com/hughski/colorhug2-firmware/commit/5e1bb64ad722a9d2d95927e305fd869b4a3a46a8">here</a>.
|
|
</p>
|
|
<p>
|
|
Furthermore, using the firmware GUID extension allows fwupd to detect firmware
|
|
updates for devices it does not know how to update.
|
|
These types of devices will however show up in the command line and GUI tools,
|
|
so the user is at least aware that updates are available.
|
|
</p>
|
|
<p>
|
|
To implement this, add an interface descriptor with class code <code>0xff</code>, subclass
|
|
code <code>0x47</code> and protocol <code>0x55</code> pointing to a string descriptor with the GUID.
|
|
If the GUID matches the <code><id></code> obtained from the AppStream metadata then the
|
|
device will be shown.
|
|
An example commit to the ColorHug project can be found
|
|
<a href="https://github.com/hughski/colorhug2-firmware/commit/f974638ac17b0e50f21987e2f1d982374cabe22c">here</a>.
|
|
</p>
|
|
|
|
<h2>Offline Updates Lifecycle</h2>
|
|
<p>
|
|
Offline updates are done using a special boot target which means that the usual
|
|
graphical environment is not started. Once the firmware update has completed the
|
|
system will reboot.
|
|
</p>
|
|
<p>
|
|
Devices go through the following lifecycles:
|
|
</p>
|
|
<ol>
|
|
<li>created → <code>SCHEDULED</code> → <code>SUCCESS</code> → deleted</li>
|
|
<li>created → <code>SCHEDULED</code> → <code>FAILED</code> → deleted</li>
|
|
</ol>
|
|
<p>
|
|
Any user-visible output is available using the <code>GetResults()</code> D-Bus method, and
|
|
the database entry is only deleted once the <code>ClearResults()</code> method is called.
|
|
</p>
|
|
<p>
|
|
The results are obtained and cleared either using a provider-supplied method
|
|
or using a small SQLite database located at <code>/var/lib/fwupd/pending.db</code>
|
|
</p>
|
|
|
|
<h2>Adding Trusted Keys</h2>
|
|
<p>
|
|
Installing a public key to <code>/etc/pki/fwupd</code> allows firmware signed with a
|
|
matching private key to be recognized as trusted, which may require less
|
|
authentication to install than for untrusted files.
|
|
By default trusted firmware can be <b>upgraded</b> (but not downgraded)
|
|
without the user or administrator
|
|
password.
|
|
</p>
|
|
<p>
|
|
Only very few keys will be installed <i>by default</i>. These are the keys of
|
|
vendors who have a proven security track record and a thorough understanding of
|
|
public-private key security.
|
|
</p>
|
|
<p>
|
|
In particular, private keys should <b>only</b> be kept on Hardware Security
|
|
Mechanisms, and used on machines (or virtual machine) that have limited network
|
|
access, or networking completely disabled.
|
|
The machine and any backups also need to be kept physically secure.
|
|
</p>
|
|
<h3>Adding a New Key</h3>
|
|
<p>
|
|
If you think your key should be added by default and trusted by all users,
|
|
please open a pull request with details about your company including items such
|
|
as a daytime phone number and any relevant security policies already in place.
|
|
</p>
|
|
|
|
<p><a href="index.html">Go back to the main page</a></p>
|
|
|
|
<p class="footer">
|
|
Copyright <a href="mailto:richard@hughsie.com">Richard Hughes 2015</a>
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html>
|