tezsign

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.

Comparison With Other Available Solutions

Feature	TezSign	Russignol	BLS Signer
Supported Devices	🥧 RPi Zero 2W, RPi 4, Radxa Zero 3W	🥧 RPi Zero 2W w/ PaperInk	🥧 RPi Zero 2W w/ PaperInk
Hardware Start Cost	< $20 USD *	~$50 USD *	~$50 USD *
Tezbake Integration	Full	Partial	Partial
Avg Signature Time	4 - 10 ms**	~6ms	~30ms
Security	🔒 Higher (Read-Only Image and Wire Proto)	🔒 High (Custom Image)	🛡️ Medium
Power Loss Safe	✅ Yes	✅ Yes	⚠️ No
Boot Time	🚀 3s **	🚀 3s	~1.5m
Multi-Device Support	✅ Yes	❌ No	❌ No
Multi-Baker Support	✅ Yes	❌ No	❌ No
Companion App	Required	Optional	No
Physical Pinlock	❌ No (App-based)	👆 Yes (Touch Screen)	👆 Yes (Touch Screen)
Auto Unlock on Boot	✅ Yes (Optional)	❌ No	❌ No
Compressed Image Size	📦 10 - 15 MB **	📦 7 MB	🐘 1.95 GB
License	📜 SSPL	📜 MIT* (partial)	📜 MIT

Note: The comparison table above is accurate as of December 2, 2025.

Disclaimer: The values for other signers in the comparison table are provided by their respective providers or users and have not been independently verified by us. If you notice any inaccuracies, please let us know.

* Shipping & taxes may apply. ** Actual speed and size may vary depending on factors such as the hardware, SD card type, and operating conditions.

Note on Power Loss: "Yes" indicates the device is hardened against corruption if power is suddenly cut.

🚀 Get Started

What you need:

• Hardware Gadget: Raspberry Pi Zero 2W, Raspberry Pi 4, or Radxa Zero 3W.
• 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 in the Yocto kernel patch at kas/meta-tezsign/recipes-kernel/linux-mainline/linux-mainline-6.18/0001-dwc2-gadget-skip-stop-xfr-on-active-dequeue.patch.

---

🏛️ Architecture

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 tezsign command-line tool) which you use to control the gadget from your host machine.

Note: If you want to run tezsign as a standalone systemd service (not in conjunction with tezbake) on Linux or macOS, please refer to the ami guide for detailed instructions.

---

⚙️ Setup

1. Download the gadget image for your specific device and the host app.

   • tezsign Releases
   • IMPORTANT: For production use, avoid images with dev in their name.

2. Use Balena Etcher (or a tool you are familiar with) to flash the gadget image to your SD card.

3. Plug the SD card into your board (e.g., Radxa Zero 3W, RPi Zero 2W).

4. 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.

5. (Linux Hosts Only) Add udev rules:

   Note: If you are installing with tezbake or using the ami, you do not need to install udev rules manually. Both tezbake and the ami handle this automatically during setup-tezsign.

   To allow your host machine to communicate with the gadget without root privileges, you need to add a udev rule. Run the helper script (it writes /etc/udev/rules.d/99-tezsign.rules and reloads udev) to install the required rule:

   sudo ./tools/add_udev_rules.sh

   After running the script, make sure your user is part of the plugdev group:

   sudo usermod -aG plugdev $USER

   You will need to log out and log back in for this group change to take effect.

The device comes preconfigured and is ready within 5 seconds of being connected.

---

✨ Initialization & Usage

After connecting the device, it should be ready within a few seconds. It's time to initialize it.

Assuming your host app is available in your path as tezsign:

1. Confirm Device Connection

   ./tezsign list-devices
   ./tezsign version

2. Initialize the Device This prompts you for a master password.

   ./tezsign init

   Warning: It is not currently possible to change this password. Please choose wisely!

3. Generate New Keys Generate the keys you need, giving them descriptive aliases.

   ./tezsign new consensus companion

   (You can use any aliases you like, not just "consensus" and "companion".)

4. List Keys & Check Status You can list all available keys on the device and check their status.

   ./tezsign list
   ./tezsign status

5. 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 status --full

   Use the BLpk and proof of possession to register the keys as a consensus or companion key. You can use a tool like tezgov to do this comfortably.

6. 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 unlock consensus companion

   (Use the same aliases you created in step 3.)

7. Start the Signer Server Finally, start the signer server. Your baker should be configured to point to this address and port.

   ./tezsign run --listen 127.0.0.1:20090

   If you want periodic host-to-gadget keep-alive frames when no writes happen, add --keep-alive:

   ./tezsign run --listen 127.0.0.1:20090 --keep-alive=100ms

   Note: Keep-alive is optional and the minimum accepted value is 10ms. At this point, tezsign is ready for baking. Make sure your baker points to it when the registered keys activate, and it will sign baking operations automatically.

---

🔒 Security

See security.md

---

🛠️ Development

See readme.dev.md