Signing Test Firmware Payloads
Firmware
In the normal vendor update flow, firmware is optionally signed and encrypted by the vendor, and then uploaded to the LVFS wrapped in a cabinet archive with a small XML metadata file to describe how the firmware should be matched to hardware.
Upon uploading, the LVFS signs the firmware and metadata XML contained in the archive and adds it to
a .jcat file also included in the image.
The original firmware is never modified, which is why the Jcat file exists as both a detached
checksum (SHA-256 and SHA-512) and a detached signature.
The LVFS uses several PKCS#7 signatures in the Jcat file.
The keys in /etc/pki/fwupd and /etc/pki/fwupd-metadata are used for per-system trust and are
currently used for “did the firmware update come from somewhere I trust” rather than “verify the
vendor signed the update” — on the logic the “signed the update” is probably already covered by
a signature on the payload that the device verifies.
Notably, The LVFS both verifies the vendor OEM → ODM → IHV relationships and assigns restrictions
on what devices each legal entity can upload for.
There’s no way to separate the keys so that you could say “only use this certificate for per-system-trust when the DMI vendor of the device is Dell” and there’s no way to do key rotation or revocation. The trusted certificate mechanism was not really designed for any keys except the static LVFS.
JCat Format
JCat is a gzip-compressed JSON catalog file, which can be used to store GPG, PKCS-7, SHA-256 and SHA-512 checksums for each file. This provides equivalent functionality to the catalog files supported in Microsoft Windows.
Each JSON file is logically divided into three structures:
FwupdJcatBlob
The ‘signature’ blob, which can be a proper detached signature like PKCS-7 or just a checksum like SHA-256.
FwupdJcatItem
Items roughly approximate single files, and can have multiple JcatBlobs assigned.
In a firmware archive there are two items, with IDs firmware.bin and firmware.metainfo.xml.
FwupdJcatFile
The container which contains one or multiple JcatItems.
Self Signing
Jcat files can be signed using a certificate and key that are automatically generated on your local computer. This means you can only verify the Jcat archive on the same computer (and probably the same user) that you use to sign the archive.
It does however mean you can skip manually generating a secret key and public key pair. If you do upload the public certificate up to a web service (for instance the LVFS) it does mean it can verify your signatures.
$ fwupdtool jcat-self-sign firmware.jcat firmware.bin
$ fwupdtool jcat-info firmware.jcat
FwupdJcatFile:
Version: 0.1
FwupdJcatItem:
ID: firmware.bin
FwupdJcatBlob:
Kind: pkcs7
Flags: is-utf8
Timestamp: 2020-03-05T12:06:42Z
Size: 0x2d9
Data: -----BEGIN PKCS7-----
MIIB9wYJKoZIhvcNAQcCoIIB6DCCAeQCAQExDTALBglghkgBZQMEAgEwCwYJKoZI
...
oDd2UcfqgdQnihpYf0NaPDYhpcP5r7dmH1XN
-----END PKCS7-----
Public Key Signing
Jcat can of course sign the archive with proper keys too. Here we will generate a private and public key ourselves, but you should probably talk to your IT department security team and ask them how to get a user certificate that’s been signed by the corporate CA certificate.
Lets create our own certificate authority (CA) and issue a per-user key for local testing. Never use these in any kind of production system!
$ ../../contrib/build-certs.py
$ ls ACME-CA.* rhughes*
ACME-CA.key ACME-CA.pem rhughes.csr rhughes.key rhughes.pem rhughes_signed.pem
Then we can actually use both files:
$ fwupdtool jcat-sign firmware.jcat firmware.bin rhughes_signed.pem rhughes.key
FwupdJcatFile:
Version: 0.1
FwupdJcatItem:
ID: firmware.bin
FwupdJcatBlob:
Kind: pkcs7
Flags: is-utf8
Timestamp: 2020-03-05T12:16:30Z
Size: 0x373
Data: -----BEGIN PKCS7-----
MIICZwYJKoZIhvcNAQcCoIICWDCCAlQCAQExDTALBglghkgBZQMEAgEwCwYJKoZI
...
8jggo0FbhDSs8frXhr1BHKBktOPKEbA3sETxlbHViYt6oldpi1uszV0kHA==
-----END PKCS7-----
Lets verify this new signature:
$ fwupdtool jcat-verify firmware.jcat
firmware.bin:
FAILED pkcs7: failed to verify data for O=ACME Corp.,CN=ACME CA: Public key signature verification has failed. [-89]
FAILED: Validation failed
Validation failed
Ahh, of course; we need to tell Jcat to load our generated CA certificate:
$ fwupdtool jcat-verify firmware.jcat --public-keys .
firmware.bin:
PASSED pkcs7: O=ACME Corp.,CN=ACME CA
We can then check the result using
$ fwupdtool jcat-export firmware.jcat
Wrote ./firmware.bin-com.redhat.rhughes.p7b
$ certtool --p7-verify --infile firmware.bin-com.redhat.rhughes.p7b --load-data firmware.bin --load-ca-certificate=ACME-CA.pem
Loaded CAs (1 available)
eContent Type: 1.2.840.113549.1.7.1
Signers:
Signer's issuer DN: O=ACME Corp.,CN=ACME CA
Signer's serial: 4df758978d0601c6500ab6f266963916d8b7ab33
Signature Algorithm: RSA-SHA256
Signature status: ok
Large Payloads
It may be impractical to load the entire binary into RAM for verification. For this use case, jcat supports signing the checksum of the payload as the target rather than the payload itself.
$ fwupdtool jcat-self-sign firmware.jcat firmware.bin sha256
$ fwupdtool jcat-sign firmware.jcat firmware.bin rhughes_signed.pem rhughes.key pkcs7 sha256
$ fwupdtool jcat-info firmware.jcat
FwupdJcatFile:
Version: 0.1
FwupdJcatItem:
ID: firmware.bin
FwupdJcatBlob:
Kind: sha256
Flags: is-utf8
Timestamp: 2023-12-15T16:38:11Z
Size: 0x40
Data: a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447
FwupdJcatBlob:
Kind: pkcs7
Target: sha256
Flags: is-utf8
Timestamp: 2023-12-15T16:38:15Z
Size: 0xdcc
Data: -----BEGIN PKCS7-----
MIIKCwYJKoZIhvcNAQcCoIIJ/DCCCfgCAQExDTALBglghkgBZQMEAgEwCwYJKoZI
...
Zjb6fuKL5Rr/ouoImn+x1cYJyqRMmCxpLG9GrXR9Ag==
-----END PKCS7-----
$ fwupdtool jcat-verify firmware.jcat --public-keys ACME-CA.pem
firmware.bin:
PASSED pkcs7: O=ACME Corp.,CN=ACME CA
NOTE: Only JCat v2.0.0 and newer supports the checksum of the payload functionality, and you should also add signatures without using target if you need to support older versions. Additionally, older JCat versions deduplicate the blobs by just the blob kind, so you want to make sure that the signature added with target is added before the signature added without.
Testing
Download a firmware from the LVFS, and decompress with gcab -x — we can now
validate the signatures are valid:
certtool --p7-verify --infile=firmware.bin.p7b --load-ca-certificate=/etc/pki/fwupd/LVFS-CA.pem --load-data=firmware.bin
Lets create a Jcat file with a single checksum:
$ fwupdtool jcat-self-sign test.jcat firmware.bin sha256
$ fwupdtool jcat-info test.jcat
FwupdJcatFile:
Version: 0.1
FwupdJcatItem:
ID: firmware.bin
FwupdJcatBlob:
Kind: sha256
Flags: is-utf8
Timestamp: 2020-03-04T13:59:57Z
Size: 0x40
Data: bd598c9019baee65373da1963fbce7478d6e9e8963bd837d12896f53b03be83e
Now we can import both existing signatures into a Jcat file, and then validate it again.
$ fwupdtool jcat-import test.jcat firmware.bin firmware.bin.asc
$ fwupdtool jcat-import test.jcat firmware.bin firmware.bin.p7b
$ fwupdtool jcat-info test.jcat
FwupdJcatFile:
Version: 0.1
FwupdJcatItem:
ID: firmware.bin
FwupdJcatBlob:
Kind: sha256
Flags: is-utf8
Timestamp: 2020-03-04T13:59:57Z
Size: 0x40
Data: bd598c9019baee65373da1963fbce7478d6e9e8963bd837d12896f53b03be83e
FwupdJcatBlob:
Kind: gpg
Flags: is-utf8
Timestamp: 2020-03-04T14:00:30Z
Size: 0x1ea
Data: -----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
iQEcBAABAgAGBQJeVoylAAoJEEim2A5FOLrCagQIAIb6uDCzwUBBoZRqRzekxf0E
...
=0GGy
-----END PGP SIGNATURE-----
FwupdJcatBlob:
Kind: pkcs7
Flags: is-utf8
Timestamp: 2020-03-04T14:00:34Z
Size: 0x8c0
Data: -----BEGIN PKCS7-----
MIIGUgYJKoZIhvcNAQcCoIIGQzCCBj8CAQExDTALBglghkgBZQMEAgEwCwYJKoZI
...
EYOqoEV8PaVQZW3ndWEaQfyo6MgZ/WqpO6Gv2zTx1CXk0APIGG8=
-----END PKCS7-----
$ fwupdtool jcat-verify test.jcat --public-keys /etc/pki/fwupd
firmware.bin:
PASSED sha256: OK
PASSED gpg: 3FC6B804410ED0840D8F2F9748A6D80E4538BAC2
PASSED pkcs7: O=Linux Vendor Firmware Project,CN=LVFS CA
Security
Unlike Microsoft catalog files which are a signed manifest of hashes, a Jcat file is a manifest of
signatures.
This means it’s possible (and positively encouraged) to modify the .jcat file to add new
signatures or replace existing ones.
This means Jcat does not verify that the jcat file itself has not been modified, only that the individual files and signatures themselves have not been changed.
If you require some trust in that file A was signed at the same time, or by the same person as file B then the best way to do this is to embed a checksum (e.g. SHA-256) into one file and then verify it in the client software.
For instance, when installing firmware we need to know if a metadata file was provided by the LVFS
with the vendor firmware file. To do this, we add the SHA-256 checksum of the firmware.bin in the
firmware.metainfo.xml file itself, and then add both files to a Jcat archive.
The client software (e.g. fwupd) then needs to check the firmware checksum as an additional step of
verifying the signatures in the Jcat file.
Back to Firmware
If the intent is to use a test key to sign the firmware files and get installed purely offline with an unmodified fwupd package (without uploading to the LVFS) then the following instructions can be modified to suit.
First, lets verify that an existing firmware binary and metainfo file without a Jcat signature refuses to install when packaged into a cabinet archive:
$ fwupdtool build-cabinet firmware.cab firmware.bin firmware.metainfo.xml
$ fwupdmgr install firmware.cab --allow-reinstall
Decompressing… [ - ]
firmware signature missing or not trusted; set OnlyTrusted=false in /etc/fwupd/fwupd.conf ONLY if you are a firmware developer
Let’s use the test certificates we generated above.
Please do not use the unmodified ACME-CA.pem or rhughes_signed.pem files for signing any cabinet
archives you’re going to redistribute anywhere (even internally), otherwise it is going to be very
confusing to debug which rhughes_signed.pem is being used.
Lets now use the signed user key to create a Jcat file and also add a SHA256 checksum:
fwupdtool jcat-sign firmware.jcat firmware.bin rhughes_signed.pem rhughes.key
fwupdtool jcat-self-sign firmware.jcat firmware.bin sha256
We can then create the new firmware archive, this time with the self-signed Jcat file as well.
fwupdtool build-cabinet firmware.cab firmware.bin firmware.metainfo.xml firmware.jcat
Now we need to install the CA certificate to the system-wide system store.
If fwupd is running in a prefix then you need to use that instead, e.g. /home/emily/root/etc/pki/fwupd/.
$ sudo cp ACME-CA.pem /etc/pki/fwupd/
[sudo] password for emily: foobarbaz
Then, the firmware should install without needing to change OnlyTrusted in fwupd.conf.
$ fwupdmgr install firmware.cab --allow-reinstall
Writing… [***************************************]
Successfully installed firmware
Vendors are allowed to sign the Jcat with their own user certificate if desired, although please note that maintaining a certificate authority is a serious business including HSMs, time-limited and revokable user-certificates — and typically lots of legal paperwork.
Shipping the custom vendor CA certificate in the fwupd project is not possible, or a good idea, secure or practical — or how fwupd and LVFS were designed to be used. So please do not ask.
That said, if a vendor included the .jcat in the firmware cabinet archive, the LVFS will
append its own signature rather than replace it — which may make testing the archive easier.
Debugging
Using sudo fwupdtool get-details firmware.cab --verbose --verbose should indicate why the
certificate isn’t being trusted, e.g.
FuCabinet processing file: firmware.metainfo.xml
FuCabinet processing release: 1.2.3
FuCabinet failed to verify payload firmware.bin: checksums were required, but none supplied
This indicates that the fwupdtool jcat-self-sign firmware.jcat firmware.bin sha256 step was
missed as the JCat file does not have any supported checksums.