You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
118 lines
4.2 KiB
Plaintext
118 lines
4.2 KiB
Plaintext
|
|
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.
|
|
|