Homemade Jade Signature Device Using ESP32 Development Board

Author: Anony

This article introduces a method to burn firmware to the ESP32 development board on a Windows computer to create a Jade-DIY hardware signature device.

Introduction: DIY Jade

Mi Zeng provided a detailed review of the Jade hardware signer launched by Blockstream, which introduced the security model of the Jade hardware signer and some of its distinctive security features.

Because Jade's firmware is completely open source, we can make a hardware signer with the same functionality based on the same hardware as the official version of Jade (hereinafter, we will refer to them as "official version of Jade" and "Jade-DIY" respectively).

After testing, we found that although some Jade-DIYs cannot be exactly the same as the official version of Jade in terms of functionality (one of the reasons will be discussed below: hardware foundation), in terms of security features, Jade-DIY is the same as the official version of Jade. Jade-DIY has all the security features that the official version of Jade has (such as "virtual security chip" and self-erasing PIN code). This gives Jade-DIY a huge appeal because it can use relatively cheap hardware to make a signer.

Moreover, Jade-DIY is very solid in basic functions and is in no way inferior to the mainstream signature machines on the market today.

Hardware selection

In Jade's GitHub repository , there is a dedicated page that introduces the hardware that can be made into a Jade-DIY signature device. Readers need to pay attention to two aspects: (1) whether it is equipped with a camera, which is also the basis for the classification of this page; (2) whether the USB VendorID and ProductID of the hardware itself are consistent with the official version of Jade.

The latter determines whether the software wallet will recognize the Jade-DIY as Jade when we use USB to connect it. If not, it will be more troublesome to use. However, these hardware basically support Bluetooth, so you can always use Bluetooth to connect to the signer (if the software signer supports it, such as the mobile Green Bitcoin Wallet ). In addition, if you choose to use hardware with a camera, you can always use the Air-gapped interaction method (mainly scanning the code), so you don’t have to mind this issue anymore.

This tutorial is only for hardware without a camera . Among these hardware, the USB VendorID and ProductID are consistent with the retail version of Jade (the brand name is before the space, and the model is after the space):

• LILYGO T-Display
• M5Stack Basic Core
• M5Stack FIRE

For economical considerations, I chose T-Display. When I bought it, it only cost 65 yuan. Readers should be careful not to confuse it with T-Display S3 when purchasing. I bought the version numbered Q125. For convenience, you can buy a shell separately (12 yuan). It is said that the K164 version with its own shell can also be successfully produced.

The following will use T-Display as an example. The other two hardware use the same chip as T-Display, so their flashing processes are similar.

Connecting the Hardware

The USB port of T-Display is Type-C, so you should prepare a Type-C USB cable. After connecting T-Display, check whether it can start normally. Normally, it will first display the "LILYGO" icon, and then the warning message "SD card mount failed" will appear.

Then, open the Windows "Device Manager" and check if there is an item "USB-Enhanced SERIAL CH9102 (COM3)" under "Ports (COM and LPT)". If not, it means that the connection is not normal and the driver should be installed. After downloading and installing the driver, try to connect again.

If you still cannot connect after installing the driver, please try using a different USB cable (some cables only have power supply function but no data transmission function).

The two M5Stack hardware mentioned above use the same USBT chip as T-Display, so the connection can be verified in the same way.

Installing Development Tools

Download the development tools from the ESP-IDF website . Please download "ESP-IDF v5.2.2 - Offline Installer". After opening the installer, on the page where you select the installation content, you should: (1) install "Powershell support"; (2) in "Chip Targets", install at least "ESP32" and "ESP32-S3". (The first item "Framework" and the second item "ESP-IDF 5.2" must not be omitted).

After installation, try to open an ESP-IDF environment by clicking the "+" sign in the menu bar of a new PowerShell window and selecting "ESP-IDF 5.2". If your PowerShell window does not look like the one shown, try another method (such as the "Start" menu

Download Jade source code

First, make sure you have Git installed. This is a version control tool that you can use to download the source code for open source software.

In a folder of your choice, open a PowerShell window and enter the following command and run it:

 git clone --recursive https://github.com/Blockstream/Jade.git

This command line will create a new "Jade" folder and download the Jade source code.

Next comes the most important section of this tutorial.

Compile and burn the firmware

When burning firmware, you can choose to enable or not enable "Secure Boot". The function of Secure Boot is to inject a public key into the device and require the burned firmware to be signed by the public key. If the burned firmware does not have a valid signature, the device will refuse to boot. This is a useful security measure to prevent your device from being injected with firmware with malicious code by others. The DIY guide in the Jade source code repository also recommends enabling the Secure Boot function. Therefore, this tutorial also strongly recommends enabling the Secure Boot function.

The following "Experimental Flashing" section will introduce the flashing process without Secure Boot enabled; as the name suggests, this is mainly to familiarize readers with the flashing process. The "Secure Flashing" section will introduce the flashing process with Secure Boot enabled.

Note that the operation of enabling Secure Boot described here is irreversible. Once enabled, it cannot be canceled. That is, if you want to update the device's firmware in the future, you must use the same private key to sign the new firmware before flashing it. If you lose the private key that signed the firmware, you will no longer be able to update the firmware for this device.

Prepare in Advance

Python3 in CMD

Before starting to burn, please open the "Command Prompt (CMD)" on your computer, enter python3 and press Enter to execute. If it is recognized and executed correctly, you should see the following information in the window:

 Python 3.12.3 (tags/v3.12.3:f6650f9, Apr 9 2024, 14:05:25) [MSC v.1938 64 bit (AMD64)] on win32Type "help", "copyright", "credits" or "license" for more information.>>>

If the program responds by opening the Windows Store, it means that CMD cannot correctly identify and execute the corresponding version of python when it gets the command "python3", which will cause an error in the subsequent compilation. This error must be fixed. A strange but effective way is to copy "python.exe" in your Python folder, paste it into the same folder, and then rename the copy to "python3.exe".

This reminder is given because compilation errors caused by this have occurred on the two Windows computers I use (Win10 and Win11 respectively).

ESP-IDF runtime environment runtime folder

Open the "ESP-IDF 5.2" runtime environment in any folder; after opening it, it will automatically run a series of environment settings to ensure that we can use the functions of ESP-IDF. After running successfully, it will output a series of information, ending with this:

 Go to the project directory and run: idf.py build

The initial runtime environment of ESP-IDF is its installation folder, for example: ~\Espressif\frameworks\esp-idf-v5.2.2 . We need to use cd command to switch to the "Jade" folder. Assuming that the address of your "Jade" folder is D:\esp\Jade , then enter in the ESP-IDF runtime environment:

 cd D:\esp\Jade

Finally, your environment should begin like this: PS D:\esp\Jade> .

OpenSSL

To generate a private key secure enough for signing firmware, install the OpenSSL software .

Experimental Burning

Enter the following command in the ESP-IDF runtime located in the “Jade” folder:

 cp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults

This command is used to copy a configuration file from the "configs" folder to the "Jade" folder. The configuration file that needs to be copied depends on the device. The configuration file provided here is the T-Display configuration file.

If the hardware you are using is "M5Stack Basic Core", the command should be changed to:

 cp configs/sdkconfig_display_m5blackgray.defaults sdkconfig.defaults

Then, run the following command:

 idf.py buildidf.py flash monitor

The first command line will compile the source code in the folder into a firmware that can be burned into T-Display, and the second line will actually write it and restart T-Display after the flash is successful.

The above is the process of experimental flashing. You can play around with it and see what Jade-DIY can do.

If you make a mistake during the flashing process, causing the T-Display to fail to boot up or connect to the computer, you can try the steps described on this page : Try to disconnect the cable first, then press and hold the three buttons on the device at the same time, and then reconnect it to the computer.

Safe Burning

Generate configuration files

Enter the following command in the ESP-IDF runtime located in the “Jade” folder:

 ./tools/mkdefaults.py ./configs/sdkconfig_display_ttgo_tdisplay.defaults NDEBUG SECURE

After running, check whether there are three files in the "Jade" folder: sdkconfig , sdkconfig.defaults , and sdkconfig.defaults.orig .

Use Notepad to open the sdkconfig.defaults file and look for the following lines:

 CONFIG_SECURE_BOOT=yCONFIG_ESP32_REV_MIN_3=y

If these lines are missing or the above three files are missing, please run the above commands again.

Generate a private key for signing firmware

Then, run the following command in the ESP-IDF runtime environment to use the OpenSSL software to generate a private key for signing the firmware:

 openssl genrsa -out ../jade-diy-v2.pem 3072

This line will generate a private key named jade-diy-v2.pem in the parent folder of the "Jade" folder. This private key will be used in the firmware signing.

You can use another file name or specify another folder. But this requires you to go back and modify the relative address in the CONFIG_SECURE_BOOT_SIGNING_KEY= line in the sdkconfig.defaults file. From the perspective of convenience and security, you can generate a private key according to the above command; after burning, move the private key to another relatively hidden place; when you need to upgrade the firmware in the future, put the private key back in place, sign the firmware and burn it.

Generate bootloader and firmware

Run the following command in the ESP-IDF runtime environment:

 idf.py bootloaderidf.py build

The first line generates the bootloader. This is the program responsible for performing the Secure Boot functionality. The second line generates the firmware that performs the actual functionality.

When running the first line of command, the program may not run successfully because SDKCONFIG_DEFAULTS '~/Jade/sdkconfig.defaults.tmp' does not exist . At this time, you only need to run the command in the " Generate Configuration File " section above again to generate the required sdkconfig.defaults.tmp file.

Writing the Bootloader

After enabling Secure Boot, ESP-IDF will no longer automatically flash the bootloader, so we need to flash it manually.

Run this command in the ESP-IDF runtime:

 esptool.py write_flash --erase-all 0x1000 ./build/bootloader/bootloader.bin

Here, --erase-all means to clear all the contents in the flash memory (if you have tried experimental burning before, you may need this tag); and the following 0x1000 represents the location to write to the flash memory, followed by the file location of the bootloader to be written.

The appropriate write location may vary from device to device. If you do not use T-Display, please read carefully what appears on the screen during the idf.py bootloader command. It will prompt you: Secure boot enabled... (Secure boot is enabled, so the bootloader will not be burned automatically); below is a line of executable commands, including python.exe and esptool.py . You can copy this line of commands to replace the above line of commands, or find the characters starting with 0x in this line of commands, which represent the flash address, and replace 0x1000 in the above command and then execute it.

If you are unable to run this command, you may not have esptool installed correctly. You can try running pip install esptool to fix this.

Writing firmware

Run the following command in the ESP-IDF runtime environment:

 idf.py flashidf.py monitor

When running the second line, if it takes a long time to finish, you can press the "Ctrl" and "]" keys on the keyboard at the same time to finish it actively. See if T-Display (now it should be called "Jade-DIY") can start normally. You can try pressing the restart button on the top of the device.

Safe burning, done!

Update the firmware

Connect Jade-DIY, and in the ESP-IDF runtime environment under the "Jade" folder, run python jade_ota.py --noagent to update the firmware. This process may require the installation of some python dependencies, which can be solved using pip install .

Currently, the latest firmware version available for T-Display is 1.0.31 , which is behind the official version of Jade firmware.

Operation Guide

• The T-Display has three buttons. When operating Jade-DIY, the button on the top of the body is the "reset" button; pressing the two buttons on the body separately can move the cursor on the screen; to confirm the selection, press the two buttons at the same time.
• When initializing Jade-DIY ("Setup Jade"), Jade-DIY will ask you to set a 6-digit PIN code. This PIN code is extremely critical for security. However, to unlock and use Jade-DIY, you must first use an adapted software wallet to wake up Jade-DIY before you can enter the PIN code and unlock it.
  • Such software wallets include: desktop: Sparrow Wallet , Electrum Wallet ; mobile: Green Wallet . Jade-DIY can be connected to the computer via USB and to the mobile phone via Bluetooth. The Bluetooth function of Jade-DIY is turned off by default and needs to be turned on manually.
• After connecting to the software wallet, the user experience is not much different from that of mainstream hardware signers. When a transaction needs to be signed, the details of the transaction will be displayed on the screen.
• After unlocking Jade-DIY, you can set a "self-erase PIN" in "Duerase PIN". Once set, once this PIN is entered when unlocking, all contents in the device (including the encrypted seed words) will be deleted.
• Jade-DIY has the functions of most bitcoin-only signers, and can handle both single and multi-signature.

Security Analysis

What is Jade-DIY's security model?

In this tutorial, I introduced the process of flashing with Secure Boot enabled; Secure Boot is a very important security measure to deal with the risk of Jade-DIY being injected with malicious firmware. This risk is real, and currently, almost all hardware signers provide this protection (for example, Keystone will also check whether the firmware has a signature when upgrading the firmware).

After applying Secure Boot and testing, we believe that the security of Jade-DIY is the same as the official version of Jade. So how about the security of the official version of Jade?

As mentioned in Mi Zeng's review at the beginning of this article, Jade uses the design of a "virtual security chip" to deal with the trade-off between " security chip vs. open source ": in the process of encrypting and saving the seed words, Jade uses a key from a remote server (together with the local PIN code to encrypt the seed words). In the process of unlocking Jade, only by providing the set PIN code can the adapted software wallet communicate with the remote server and obtain this key. (This is also why when using the seed words saved by itself, it must work with the adapted software wallet).

Therefore, the security of this mode is greater than that of hardware signature devices that do not use security chips at all and have no additional design (such as earlier versions of Trezor signature devices).

However, compared with the signer that uses a security chip and has a self-destruction mechanism (self-destruction when the device is disassembled or after a certain number of invalid PIN codes are entered), Jade is slightly inferior in dealing with physical attacks after the device is hijacked.

Overall, Jade-DIY provides pretty good security and powerful enough features at a relatively low cost.

Long live the open source movement!

Acknowledgements

I would like to thank Mi Zeng for his helpful guidance and discussion during the writing of this article. Of course, all errors in the article are my own responsibility.