tezsign is a secure, air-gapped signing solution for Tezos consensus operations. It uses a dedicated hardware gadget (like a Raspberry Pi) connected via USB to a host machine, ensuring your keys remain isolated.
- Hardware Gadget: Radxa Zero 3 or any Raspberry Pi Zero 2W, 4, or other models with an OTG USB port. Note that the Raspberry Pi 5 is not recommended.
- SD Card: 4GB or larger. A high-quality, industrial-grade/endurance SD card is highly recommended.
NOTE: There is a known issue with the Raspberry Pi DWC2 USB driver that can cause USB stack failures. We have implemented a workaround to mitigate this, which can be found in our DWC2 patch. This is not an operational issue in itself, but you should be aware that the Linux kernel has been amended to address this.
tezsign consists of two parts:
- Gadget: The external, air-gapped device connected to the host over USB, acting as a peripheral. This is where your keys live and signing operations happen.
- Host App: Your companion application (the
tezsigncommand-line tool) which you use to control the gadget from your host machine.
-
Download the gadget image for your specific device and the host app.
-
Use Balena Etcher (or a tool you are familiar with) to flash the gadget image to your SD card.
-
Plug the SD card into your board (e.g., Radxa Zero 3, RPi Zero 2W).
-
Connect the board to your host machine.
- Important: Make sure you use a good quality USB cable and connect it to the OTG port of your board.
-
(Linux Hosts Only) Add udev rules:
To allow your host machine to communicate with the gadget without root privileges, you need to add a
udevrule. Run the helper script (it writes/etc/udev/rules.d/99-tezsign.rulesand reloadsudev) to install the required rule:sudo ./tools/add_udev_rules.sh
After running the script, make sure your user is part of the
plugdevgroup:sudo usermod -aG plugdev $USERYou will need to log out and log back in for this group change to take effect.
After the initial connection, the device will configure itself and reboot. This process takes approximately 30 seconds.
NOTE: The Radxa Zero 3 may encounter an issue where it fails to boot correctly after the initial configuration. If this occurs, wait until the LED diode stops blinking (indicating the configuration is complete), then unplug and reconnect the device. This issue appears to be related to certain SD cards, as some exhibit this behavior while others do not.
After about 30 seconds, your device should be ready. It's time to initialize it.
Assuming your host app is available in your path as tezsign:
-
Confirm Device Connection
./tezsign-host list-devices
-
Initialize the Device This prompts you for a master password.
./tezsign-host init
Warning: It is not currently possible to change this password. Please choose wisely!
-
Generate New Keys Generate the keys you need, giving them descriptive aliases.
./tezsign-host new consensus companion
(You can use any aliases you like, not just "consensus" and "companion".)
-
List Keys & Check Status You can list all available keys on the device and check their status.
./tezsign-host list ./tezsign-host status
-
Register Keys On-Chain To register your keys on the Tezos network, you will need their public key (
BLpk) and a proof of possession. You can get these details using:./tezsign-host status --full
Use the
BLpkand proof of possession to register the keys as a consensus or companion key. You can use a tool like tezgov to do this comfortably. -
Unlock Keys & Run Signer After the keys are registered on-chain, you must unlock them on the device to allow them to sign operations.
./tezsign-host unlock consensus companion
(Use the same aliases you created in step 3.)
-
Start the Signer Server Finally, start the signer server. Your baker should be configured to point to this address and port.
./tezsign-host run --listen 127.0.0.1:20090
At this point,
tezsignis ready for baking. Make sure your baker points to it when the registered keys activate, and it will sign baking operations automatically.
See security.md
See readme.dev.md