Verify firmware updates yourself

If you don’t want to rely on the NGRAVE Update Tool to verify and install a firmware update, you can also do this yourself. This requires (1) manual verification of the update files and (2) installing the update via command line.

In this tutorial we'll focus on how you can verify the integrity of a firmware update. After you've verified the update file, you can continue with this article to install the update: Install firmware updates via command line.

These are the basic steps:

  1. Download update file
  2. Download and install the NGRAVE public key (if you haven't done so already)
  3. Verify the signature of the update file
    → This will guarantee you the authenticity of the file: that it comes from NGRAVE.
  4. Verify the SHA256 hash of the update file
    → This will guarantee you the integrity of the file: that it hasn't been changed.

The examples in this tutorial are written with firmware version 1.5 Keep in mind that the file names and the SHA256 hash will be different for each new firmware version.

Linux and Mac come with GPG pre-installed, but on Windows, you'll need to install Gpg4win first. 

Step 1 - Download the update file

Download the update files from: https://www.ngrave.io/en/page/verify-and-install-firmware-update-yourself, but don’t unpack anything just yet. There are 3 files (with a different version number for each update):

  • NGraveFirmwareUpdater_1.5-tar.xz
    The update archive containing all files needed for the firmware update
  • NGraveFirmwareUpdater_1.5-manifest.txt
    A manifest file with the hash of the update archive
  • NGraveFirmwareUpdater_1.5-manifest.txt.sig
    The manifest detached signature file

Step 2 - Download and install the NGRAVE public key

To verify the cryptographic signature, NGRAVE's public key needs to be added to your system. If you haven’t done so already during a previous update, you need to add the NGRAVE public to your keyring. You only need to do this once on a computer. Once you’ve added it you can skip this step the next time.

If you’re not sure if you have already added NGRAVE’s public key, you can list all public keys on your system with this command:

gpg --list-keys

If NGRAVE’s public key is present you’ll see this in the output:

pub rsa4096 2023-04-14 [SC]
EF2448F36BD3B4DC9A472823B94E47401393E3F2
uid [ unknown] Ngrave.IO NV <gpg@ngrave.io>
sub rsa4096 2023-04-14 [E]

If it hasn’t been added yet, you can find the NGRAVEs public key here: https://keys.openpgp.org/vks/v1/by-fingerprint/EF2448F36BD3B4DC9A472823B94E47401393E3F2.
Save this as a file onto your computer and name it ngrave.gpg.

To add NGRAVE’s key to your keyring, open the location where you stored the file ngrave.pgp in a command line window and type this command:

gpg --import ngrave.gpg

The output will tell you that the key was imported:

gpg: key B94474013933F2: public key "Ngrave.IO NV <gpg@ngrave.io>"imported
gpg: Total number processed: 1
gpg: imported: 1

Step 3 - Verify the signature of the manifest file

Open the location where you stored the update file in a command line window and type this command

gpg --verify ./NGraveFirmwareUpdater_1.5-manifest.txt.sig

The output (see below) should tell you that this is a Good signature from "Ngrave.IO NV <gpg@ngrave.io>".

'./NGraveFirmwareUpdater_1.5-manifest.txt'
gpg: Signature made Wed 10 April 2024 16:41:39 CEST
gpg: using RSA key EF2448F36BD3B4DC9A472823B94E47401393E3F2
gpg: Good signature from "Ngrave.IO NV <gpg@ngrave.io>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: EF24 48F3 6BD3 B4DC 9A47 2823 B94E 4740 1393 E3F2

You may be alarmed by the "Warning: this key is not certified with a trusted signature"
at the end. This warning appears because GPG has no way of automatically trusting keys and because you have not explicitly marked the public key as trusted in your own instance of GPG. Normally what you would do is meet with someone using some kind of out-of-bounds communication. One of the best ways to do this is to exchange public keys in person. That way you can be absolutely sure that the public key came from them.

We have published our key on various key servers, so you can double-check it: 

Step 4 - Verify the SHA256 hash of the update archive

You can calculate the SHA256 hash of the update file with this command:

shasum -a 256 NGraveFirmwareUpdater_1.5.tar.xz

The output of this commands should look like this:

f3987cbf7273a128b4aadd57aa05ac3cc525874842a7ae889e9dc1174ba3b973  NGraveFirmwareUpdater_1.5.tar.xz

Compare the output of this command with the SHA256 hash that you can see when you open the manifest file you downloaded. It should be exactly the same and this confirms that the manifest file you downloaded contains the exact hash that NGRAVE published.

 

Next step

Now that you’ve verified the authenticity and integrity of the update archive, you can proceed to install the firmware update on your ZERO. See Install firmware updates via command line.

 

FAQ verifying signatures

How do I open a command line window in a certain location?

In a command line window you can browse to any location on your computer. But you might find it easier to open a command line window in the exact location where your downloaded files are.

This is easy to do:

  • Mac: In Finder, select a folder, right-click it and select Services >> New Terminal at Folder.
  • Windows: In the address bar of Windows Explorer, type cmd and press enter.
  • Linux: On Ubuntu based systems you can select a folder, right-click on it, and then select Open in Terminal. The procedure may vary a bit on other Linux distros.
Why is there both a SHA256 hash and a detached signature file?

Verifying the hash guarantees that the update archive wasn’t tampered with. But because the archive and the hash are offered on the same website, there is still another possible avenue of attack: an attacker could gain control of our website and offer an altered version of the firmware and a matching hash.

Cryptographically signing the hash with NGRAVE's key helps protect against attackers that might attempt to modify the hash.

How to verify Gpg4win? (Windows only)

On Windows you need to install Gpg4win before you can verify signatures with GPG. But how can you verify the integrity of the Gpg4win installer? Obviously you can’t do this with GPG before it is installed on your system.

We’ll briefly go through the options. For a more complete tutorial, please check the instructions from Gpg4win:

There are 3 additional ways to check the integrity and the publisher of the Gpg4win installer; Feel free to use all 3 methods.

1/ Method A: UAC 
When trying to run the installer on Windows, the User Access Control dialog will show the publisher, check that it is the one you expected it to be.


2/ Method B: file properties
A second way is to use the file properties in the explorer. Right click on the installer -> properties -> digital signatures -> Details of signatures. (Try this if no publisher is shown by the UAC in rare cases after a download with Firefox or Iridium (Chromium). For details see T3379.)

3/ Method C: signtool
A third way is to use MSDN: SignTool which is a part of the Microsoft development tools. You’ll need to install the Windows SDK before you can use SignTool. Then open open a command line window, navigate to the folder and use this command:

SignTool verify /pa /v gpg4win*.exe