NOTE: This release does not yet support validator signing! For progress on that, please watch PR#55 on the KMS repo, which is the last hurdle for unlocking this capability.
Tendermint Key Management System (KMS), a.k.a. tmkms, is an interface to Hardware Security Modules (HSMs), namely YubiHSM2 devices from Yubico, and soon, the Ledger Nano S. It’s intended to be run alongside Cosmos Validators, ideally on separate physical hosts, providing defense-in-depth for online validator signing keys as well as a central signing service that can be used when operating multiple validators in several Cosmos Zones.
We’ve just released tmkms v0.0.1 which contains an initial preview of the KMS’s functionality. Specifically, this release is capable of generating and listing keys within YubiHSM2s as well as a signing stress test to ensure the software is stable and robust.
As noted at the top of this post, it cannot yet be used for validator signing, but we are very close to landing that functionality (hopefully in the next few days). The current release is a bit rough around the edges and doesn’t yet have full functionality, but we’re releasing early so you can start playing around with it.
This thread provides a quick tour of the available functionality, as well as the steps needed to install Tendermint KMS.
Installation
NOTE: A detailed installation guide is also available in the README. See also: Supported Platforms.
The following is a step-by-step guide to install the initial release of the KMS. These instructions will largely remain the same for future versions of the KMS.
1. Install Rust
tmkms is written in Rust and you will need a Rust compiler to install it. There are two ways to install the Rust compiler:
a. rustup
The rustup utility provides a simple and convenient way to install Rust:
$ curl https://sh.rustup.rs -sSf | sh
b. OS packages
The Rust compiler has been packaged by several operating systems. Exact install instructions will depend on your OS, but here are a few common options:
- Debian/Ubuntu:
apt install rustc cargo - RedHat/CentOS: See https://www.softwarecollections.org/en/scls/rhscl/rust-toolset-7/
2. Install C compiler and pkg-config
You will need a C compiler for your OS (i.e. gcc or clang), as well as the pkg-config utility installed in order to compile the KMS.
3. Install libusb
KMS uses libusb to communicate with HSMs. You will need to have it installed in order for KMS to compile:
Make sure to install libusb 1.0+! Detailed instructions for installing proper libusb versions can be found in the tmkms README’s Install section.
4. Install tmkms using cargo
Run the following command to install tmkms using Rust’s “cargo” packaging utility:
$ cargo install tmkms
After running this you should see the following:
$ cargo install tmkms
Updating registry `https://github.com/rust-lang/crates.io-index`
Installing tmkms v0.0.1
[...]
Compiling tmkms v0.0.1
Finished release [optimized] target(s) in 1m 34s
After this is complete, tmkms is installed!
Configuration
tmkms uses a configuration file called tmkms.toml, which by default it looks for in the same directory as the KMS was launched from, or you can override the path with the -c /path/to/kms.toml command line argument.
An example tmkms.toml file can be found at:
YubiHSM2 Setup
NOTE: A more powerful YubiHSM2 setup subcommand is coming to tmkms soon! Stay tuned for details.
tmkms contains (almost) everything you need to set up a YubiHSM2 from scratch in a self-contained way with no additional utilities. The instructions below take you through the setup process step-by-step.
1. Detect YubiHSM2
The tmkms yubihsm detect subcommand can be used to locate your YubiHSM2:
Passing the -v command-line argument enables detailed debugging information:
2. Generate Ed25519 signing key
All YubiHSM key management commands are available under the tmkms yubihsm keys subcommand. Run tmkms yubihsm keys help for more information.
The tmkms yubihsm keys generate subcommand can be used to generate an HSM-backed signing key, (soon) suitable for use as your validator key. Every key in the YubiHSM2 has a numbered ID between 1-65535. Since we’re generating the first key in this HSM, we’ll use key ID #1:
If you see this, you’ve successfully generated your first private signing key in the YubiHSM2!
3. List signing keys
The tmkms yubihsm keys list subcommand will list all keys in the detected HSM:
4. Run signing stress test
The tmkms yubihsm test subcommand performs a stress test against the YubiHSM2. It takes the key ID# of a signing key to use for the test as an argument. Since we just created key #1, that’s what we’ll pass as an argument:
Pass -v to enable detailed debugging:
The stress test should continue running even if signing errors occur. This means you should be able to remove the YubiHSM2 from its USB slot and reinsert it (potentially in a different slot!) and signing should immediately resume when it becomes available again:
If tmkms yubihsm test crashes instead of resuming signing, you have found a critical bug! In the event this does happen, please open an issue on the tmkms GitHub issue tracker.
Thanks for reading this, and please post in this thread if you need help or even just to let us know that it’s working for you.