aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md46
1 files changed, 37 insertions, 9 deletions
diff --git a/README.md b/README.md
index b470b52..a30680a 100644
--- a/README.md
+++ b/README.md
@@ -123,11 +123,11 @@ A hashsig private key is a Merkle tree of one-time signing keys, which can
be used to sign a finite number of messages. Since they don't rely on
"hard math" for security, hashsig schemes are quantum-resistant.
-This hashsig code is a clean-room implementation of draft-mcgrew-hash-sigs.
+This hashsig code is a clean-room implementation of RFC 8554.
It has been shown to interoperate with the Cisco reference code (each can
verify the other's signatures).
-Following the recommendations of the draft, we only store the topmost hash
+Following the recommendations of the RFC, we only store the topmost hash
tree (the "root tree") in the token keystore; lower-level trees are stored
in the volatile keystore, and are regenerated upon a system restart.
@@ -253,26 +253,54 @@ impose arbitrary delays between any two operations at the pkey layer.
## Key backup ##
+There are two scenarios that could be described as "key backup."
+
+1. In the first scenario, keys are copied from one HSM to another, e.g. to
+provision a new HSM from an offline master, or to duplicate an HSM for
+load-balancing purposes.
+
The key backup mechanism is a straightforward three-step process,
mediated by a Python script which uses the Python client
implementation of the RPC mechanism. Steps:
-1. Destination HSM (target of key transfer) generates an RSA keypair,
+a. Destination HSM (target of key transfer) generates an RSA keypair,
exports the public key (the "key encryption key encryption key" or
"KEKEK").
-2. Source HSM (origin of the key transfer) wraps keys to be backed up
- using AES keywrap with key encryption keys (KEKs) generated by the
- TRNG; these key encryption keys are in turn encrypted with RSA
- public key (KEKEK) generated by the receipient HSM.
+b. Source HSM (origin of the key transfer) wraps the key to be backed up
+ using AES keywrap with a transit key encryption key ("transit KEK")
+ generated by the TRNG; this transit KEK is in turn encrypted with the
+ KEKEK public key generated by the destination HSM.
-3. Destination HSM receives wrapped keys, unwraps the KEKs using the
- KEKEK then unwraps the wrapped private keys.
+c. Destination HSM receives the wrapped key and encrypted transit KEK. It
+ decrypts the transit KEK using the KEKEK private key, then unwraps the
+ wrapped private key.
Transfer of the wrapped keys between the two HSMs can be by any
convenient mechanism; for simplicity, `cryptech_backup` script bundles
everything up in a text file using JSON and Base64 encoding.
+Note that exporting a hashsig key is a little different than exporting an
+RSA or EC key. Since the hashsig key is a tree of one-time signing keys,
+we cannot risk having two HSMs signing with the same one-time signing key,
+so exporting a hashsig key involves partitioning the key space; the source
+and destination HSMs can each generate up to 2^(L*h-1) signatures. If the
+keyspace cannot be successfully partitioned, the export operation will
+return HAL_ERROR_HASHSIG_KEY_EXHAUSTED.
+
+2. In the second scenario, keys are copied off of the HSM for external
+storage, e.g. if the signer has more keys than will fit in the HSM
+keystore.
+
+In this case, there is no KEKEK, and keys are wrapped with the HSM's
+Master Key, so they can only be re-imported to the same HSM.
+
+Note that, again, hashsig keys are special. To avoid re-using key state,
+the export operation disables the hashsig key, so the user is forced to
+delete the key from the HSM, and re-import it in order to continue using
+it. Likewise, the user must re-export the key after using it, because the
+internal state will have changed.
+
## Multiplexer daemon ##