From ac362e65661bfeb91f49cbe90b8bcbeeda5009ad Mon Sep 17 00:00:00 2001
From: Alexander Vdolainen <avdolainen@zoho.com>
Date: Thu, 16 Jun 2016 03:30:02 +0300
Subject: [PATCH] added a little bit of sxt key description;

---
 doc/sxtkey.txt | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 doc/sxtkey.txt

diff --git a/doc/sxtkey.txt b/doc/sxtkey.txt
new file mode 100644
index 0000000..8ab355f
--- /dev/null
+++ b/doc/sxtkey.txt
@@ -0,0 +1,54 @@
+I. SXT key container description
+-----------------------------
+
+1. Private keys store description
+The following format used to store a private key:
+
+(<key-type> "<base64 encoded key data>")
+
+Where:
+  - key-type is a type of the key:
+    * ppkp-ed25519
+  - base64 is an encoded private key it self consists of:
+    <MAGIC VERSION SIGN><8bit flags><key-type><cipher-name><kdf-name><kdf-opts><public-key><private-key-data>
+
+NOTE:
+ Each key may contain a 64bit special hash, but this is an optional one.
+ Key also might be encrypted with password key i.e. password thus private-key-data might be encrypted,
+ might not.
+
+ * MAGIC VERSION SIGN is just a data points to the container version used, for the first one this is: 0xbeef0101
+ * 8bit flags contains the following ones:
+   - (1 << 1) - if set - there are hash within the key
+   - (1 << 2) - if set - key is encrypted and require a password key to decrypt
+ * key-type - is the same key-type as it pointed above
+ * cipher-name and kdf-name is a plain text name of kdf and cipher used to encrypt the key, or "none" if key isn't
+   encrypted
+ * kdf-opts is an options for kdf (in case of bcrypt this is a salt and passes number)
+ * public-key is a public key
+ * private-key-data - this is a data contains all private key information (this data might be encrypted),
+   this area contains:
+    <32bit random><32bit random><public-key><private-key><64bit hash><8bit zero padding>
+
+At the moment of this document creation i'm planning to support ed25519 keys only.
+
+II. SXT keys management tools
+-----------------------------
+
+1. Key generation
+To generate a key a special tool exists: sxtkeygen
+ > sxtkeygen --type <type> --name <name> --passphrase --path <file prefix=""> --hash <64bit hash>
+   * type will ed25519 (others doesn't supported yet) - it's required value 
+   * name is optional will defaults to <type> if not pointed
+   * passphrase is optional, if pointed will required to input a passphrase 
+     to encrypt the key (taptap in the terminal)
+   * path is optional, points to the path where public/private keys files 
+     will located, defaults to the current working directory.
+   * hash is an optional - set it if you want to store an additional hash within the key
+
+i.e. the output will be two ones:
+
+  <path>/<name||type>.pub # public key
+
+  <path>/<name||type>.ppkp # private key
+