diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 46 |
1 files changed, 37 insertions, 9 deletions
@@ -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 ## |