Merge pull request #216 from zramsay/key-management

docs: key management guide

docs/guide/key-management.md

@@ -1,14 +1,179 @@
 # Key Management
 
-Here we explain a bit how to real with your keys, using the `basecli keys` subcommand.
+Here we explain a bit how to work with your keys, using the `basecli keys` subcommand.
 
-**TODO**
+**Note:** This keys tooling is not considered production ready and is for dev only.
 
-## Creating keys
-
-Create the keys and store a key phrase. No other way to recover it.
+We'll look at what you can do using the six sub-commands of `basecli keys`:
 
 ```
+new
+list
+get
+delete
+recover
+update
+```
+
+## Create keys
+
+`basecli keys new` has two inputs (name, password) and two outputs (address, seed).
+
+First, we name our key:
+
+```shelldown
+basecli keys new alice
+```
+
+This will prompt (10 character minimum) password entry which must be re-typed. 
+You'll see:
+
+```
+Enter a passphrase:
+Repeat the passphrase:
+alice		A159C96AE911F68913E715ED889D211C02EC7D70
+**Important** write this seed phrase in a safe place.
+It is the only way to recover your account if you ever forget your password.
+
+pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset
+```
+
+which shows the address of your key named `alice`, and its recovery seed. We'll use these shortly.
+
+Adding the `--output json` flag to the above command would give this output:
+
+```
+Enter a passphrase:
+Repeat the passphrase:
+{
+  "key": {
+    "name": "alice",
+    "address": "A159C96AE911F68913E715ED889D211C02EC7D70",
+    "pubkey": {
+      "type": "ed25519",
+      "data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
+    }
+  },
+  "seed": "pelican amateur empower assist awkward claim brave process cliff save album pigeon intact asset"
+}
+```
+
+To avoid the prompt, it's possible to pipe the password into the command, e.g.:
+
+```
+echo 1234567890 | basecli keys new fred --output json
+```
+
+After trying each of the three ways to create a key, look at them, use:
+
+```
+basecli keys list
+```
+
+to list all the keys:
+
+```
+All keys:
+alice		6FEA9C99E2565B44FCC3C539A293A1378CDA7609
+bob		A159C96AE911F68913E715ED889D211C02EC7D70
+charlie		784D623E0C15DE79043C126FA6449B68311339E5
+```
+
+Again, we can use the `--output json` flag:
+
+```
+[
+  {
+    "name": "alice",
+    "address": "6FEA9C99E2565B44FCC3C539A293A1378CDA7609",
+    "pubkey": {
+      "type": "ed25519",
+      "data": "878B297F1E863CC30CAD71E04A8B3C23DB71C18F449F39E35B954EDB2276D32D"
+    }
+  },
+  {
+    "name": "bob",
+    "address": "A159C96AE911F68913E715ED889D211C02EC7D70",
+    "pubkey": {
+      "type": "ed25519",
+      "data": "2127CAAB96C08E3042C5B33C8B5A820079AAE8DD50642DCFCC1E8B74821B2BB9"
+    }
+  },
+  {
+    "name": "charlie",
+    "address": "784D623E0C15DE79043C126FA6449B68311339E5",
+    "pubkey": {
+      "type": "ed25519",
+      "data": "4BF22554B0F0BF2181187E5E5456E3BF3D96DB4C416A91F07F03A9C36F712B77"
+    }
+  },
+]
+```
+
+to get machine readable output.
+
+If we want information about one specific key, then:
+
+```
+basecli keys get charlie --output json
+```
+
+will, for example, return the info for only the "charlie" key returned from the previous `basecoin keys list` command.
+
+The keys tooling can support different types of keys with a flag:
+
+```
+basecli keys new bit --type secp256k1
+```
+
+and you'll see the difference in the `"type": field from `basecli keys get`
+
+Before moving on, let's set an enviroment variable to make `--output json` the default.
+
+Either run or put in your `~/.bash_profile` the following line:
+
+```
+export BC_OUTPUT=json
+```
+
+## Recover a key
+
+Let's say, for whatever reason, you lose a key or forget the password. On creation, you were given a seed. We'll use it to recover a lost key.
+
+First, let's simulate the loss by deleting a key:
+
+```
+basecli keys delete alice
+```
+
+which prompts for your current password, now rendered obsolete, and gives a warning message. The only way you can recover your key now is using the 12 word seed given on initial creation of the key. Let's try it:
+
+```
+basecli keys recover alice-again
+```
+
+which prompts for a new password then the seed:
+
+```
+Enter the new passphrase:
+Enter your recovery seed phrase:
+strike alien praise vendor term left market practice junior better deputy divert front calm
+alice-again	CBF5D9CE6DDCC32806162979495D07B851C53451
+```
+
+and voila! You've recovered your key. Note that the seed can be typed our, pasted in, or piped into the command alongside the password.
+
+To change the password of a key, we can:
+
+```
+basecli keys update alice-again
+```
+
+and follow the prompts.
+
+That covers most features of the keys sub command.
+
+<!-- use later in a test script, or more advance tutorial?
 SEED=$(echo 1234567890 | basecli keys new fred -o json | jq .seed | tr -d \")
 echo $SEED
 (echo qwertyuiop; echo $SEED stamp) | basecli keys recover oops
@@ -16,5 +181,4 @@ echo $SEED
 basecli keys get fred -o json
 basecli keys get derf -o json
 ```
-
-You can type it in to recover... try to do this by hand.
+-->