From d62181e28066c48371dc797bf417a70aa31f0a7e Mon Sep 17 00:00:00 2001
From: Alexander Vdolainen <avdolainen@zoho.com>
Date: Wed, 6 Jul 2016 03:16:30 +0300
Subject: [PATCH] doc: ppkp(sxt) container doc added;

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

diff --git a/doc/ppkpkeys.txt b/doc/ppkpkeys.txt
new file mode 100644
index 0000000..a1ac772
--- /dev/null
+++ b/doc/ppkpkeys.txt
@@ -0,0 +1,117 @@
+
+Doc: PPKP key container used in sxmp framework
+Description: Container format format description, generic tools description.
+Validity: 0.5.0-
+
+0. Terms used
+=============
+1. Integer values:
+ * u8 - unsigned 8bit
+ * u16 - unsigned 16bit
+ * u32 - unsigned 32bit
+ * u64 - unsigned 64bit
+
+2. Data sign:
+ * :B64 - base64 encoded data
+ * :CRYPT - a data area might be crypted
+
+A. PPKP key container general information
+=========================================
+1. Supported types (for valid versions):
+ * ppkp-ed25519 - Edwards-curve Digital Signature Algorithm (EdDSA) is a
+ digital signature scheme using a variant of Schnorr signature based on
+ Twisted Edwards curves.
+
+2. Supported features:
+ * Crypting private key with passkey i.e. password
+ * Storing custom u64 value (called custom hash)
+
+3. Information storage methods:
+ * integer values stored in network endianess (i.e. big endian)
+ * all values, except plain text container marks stored as base64 encoded
+ data
+ * key stored as an S-expression
+ * different checking for valid data exists:
+   ** public key verified by hash value stored in public key and hash itself
+   as a separate data
+   ** S-expression validity
+   ** private key verified by:
+      *** magic number
+      *** plain text and encoded text for key type
+      *** public key stored in two places, one of them might be encrypted by
+      passkey
+      *** validity of flags
+      *** random u32 numbers
+
+4. Recommendations:
+Store the private keys encrypted with passkey. Use custom u64 hash for your
+application level purposes and to verify keys if possible/required.
+
+B. PPKP key container structure
+===============================
+1. General plaintext format.
+ a. Private keys
+    Private keys stored as follows:
+    (<key-type> ":B64")
+ b. Public keys
+    Public keys stored as follows:
+    (<key-type> 'public ":B64" ":B64")
+
+2. Private key format description:
+Private key encoded data might be presented as follows:
+---
+<MAGIC text><u8: flags><Type text><Cipher name text><KDF name text>
+<KDF options><public key><:CRYPT private key format>
+---
+Where:
+ * MAGIC text *must* contain <u32: length of the magic text>,
+   magic itself with following possible values:
+   ** 0xbeef0101 - container v.1
+ * u8: flags is a raw u8 value where the following bits used:
+   ** 1 - set if key contain a custom hash differes from 0
+   ** 2 - set if private key contents encrypted by passkey
+ * Type text contain <u32: length of type text> and the following text itself,
+   must be equal to the plaintext one, is not - format is invalid
+ * Cipher name text contain <u32: length of name length>, text name of cipher
+   itself. If key isn't encrypted *must* contain 'nil' value.
+ * KDF name text contain <u32: length of kdf name text>, KDF name itself,
+   If key isn't encrypted value *must* be 'nil'.
+ * KDF options contain <u32: length of the KDF options>, options data following.
+   The content may depends on KDF/Cipher used. Follow the reference for
+   supported key types:
+   ** ppkp-ed25519 uses aes128-cbc for cipher and bcrypt as KDF (OpenBSD
+   implementation of bcrypt_pbkdf()) and in this case the following content will
+   valid:
+   *** (non-encrypted) <u32 1><'nil'><u32 2> :
+   **** u32 1 is a length of the following text 'nil'
+   **** u32 2 is a zero
+   *** (encrypted) <u32 1><salt><u32 2>
+   **** u32 1 is a length of salt random data
+   **** salt random data used as a salt
+   **** u32 2 is a number of rounds used by bcrypt
+ * public key contain <u32 1><u32 2><public key data>
+   ** u32 1 - is a length of the following data
+   ** u32 2 - is a length of the public key data
+   i.e. u32 1 - u32 2 *must always* be equal to sizeof u32
+ * private key format (going to be encrypted in case of enabled encryption)
+   described below.
+
+Private key format used to store and verify private key consists of the
+following:
+---
+<u32 random1><u32 random2><u32: pubkey length><public key data>
+<u32: private key length><private key data><u64: custom hash value><u8 padding>
+---
+Where:
+ * random1 *must* be equal to random2
+ * padding has a zero value
+
+3. Public key format description
+Public key has two base64 encoded record, first contain the following:
+---
+<u32 length of the pubkey data><public key data><u64 custom hash>
+---
+Second record contain <u64 custom hash>
+
+NOTE: custom hashes *must* equals.
+