[Cryptech-Commits] [sw/libhal] 03/03: Update readme

[git at cryptech.is]

This is an automated email from the git hooks/post-receive script.

paul at psgd.org pushed a commit to branch import_export_raw
in repository sw/libhal.

commit 57298bf578117a299b151bf2b661487cbb8a67e7
Author: Paul Selkirk <paul at psgd.org>
AuthorDate: Tue Dec 3 10:19:07 2019 -0500

    Update readme
---
 README.md | 46 +++++++++++++++++++++++++++++++++++++---------
 1 file 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 ##