libsxmp/doc/ppkpkeys.txt

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.