Blocks

All the data that goes between [parties] is packed into signed and optionally encrypted protected block. Such a block, in turn, consist of a hierarchy of unified formatted data with explicit format type mark, we call it basic block and treatt it as a binary sequence.

Basic block

The main purpose of the

It supports various data formats (say, BSON amd JSON, XML), of which it only requires that the format allows minimally typed structures (objects). It oculd be described in the EBNF notation as:

block           = format_mark, formatted_block
format_mark     = "\x00" | "{" | "<"
formatted_block = ? some formatted structure ?

Format mark "\x00" (zero byte) stands for BOSS notation (where is is coded as a zero byte prepending actual data), { is the usual first character of the JSON file, and < is an opening of the XML file.

The inner structure contains key-value sequence with string, non repeating keys. The order is not significant. The structure often contains inner blocks, which are encoded the same way. We recommend using the same block format for all nested blocks, but is is not obligatory. Nested blocks should be treated as binary sequences. With the text formats, like JSON and XML, use base64-encoded text.

Protected block

Is a structire with nested structures, with signatures at the outer layer, e.g. it is a signed block.

{
    "signarues": {
        "key1_id": "key1_signature", 
        // there could be any number of signatures
    },
    "signed_block": block 
}

Each signature has some string id that refers a public key that must be included in the signed_block. If is is missing, the protected block should be considered tampered and is discarded without further inspection.

Signed block

{ 
    "keys": {
        "key1_id": {
            "type": "rsa",
            "public_key": packed_public_key,
        },
        // more key records
    },
    "data": block // The data itself.
}   

Here should be defined each key from the signatures section, and any key, defined here should have a valid signature above. Otherwise the block is considered tampered and is discarded without further inspection.

Data block

Structure

Is the innermost structure containig actual data payload, encryption and keys information.

{
    "encryption": {
        "mode": mode_string,
        "key_data": [
            {
                "derivation_method": optional_string,
                "password_hint": optional_text_hint, 
                "fingerprint": binary_fingerprint,
                "encrypted_key": binary_encrypted_data_key
            },
            //....
        ]
    },
    "expires_at": date_time,
    "open_payload": {
        // Optional section
    },
    "payload": block
}

At the moment ATTESTA uses 2 modes of encryption:

mode_string meaning
open not encrypted
aes256/conuner aes256 in counter mode, with IV

Parties can, meanwhile, use any method of theri choice, as ATTESTA rarely needs to access block internals, in which case one of above mentioned is used.

The field expires_at should be respected by all involved parties. Expired block should be completely deleted with all is copies from all available sotages. It is important to respect block expiration.

The open_payload can be used to store any data that should be visible to all.

Key data

The block is often intended to be accessible for more than one party. For example, it is reasonable to be able to decrypt some message by both sender and recipient, which means there should be at leaas 2 keys that can decrypt the message, and very ofthen this number can be significally higher. To make it, ATTESTA requires each ecnrypted data block to have at least one key_data item.

Each key_data entry contain a key fingerprint, wich is a hash, and the ecrypted datakey. The `datakey` can decrypt the payload, but it is also encrypted by some key known only to the intended parties.

The party looks through its key rings looking for keys with matching fingerprints and try them to decrypt the payload.

Optional derivation_method is used instead of the fingerprint when the key is a password. If it is present, the party can ask user, using optinoal password hint, to enter the password to decypt data. The derivation methods proposed are:

derivation_method meaning
argon2i see Argon2 papers
AKDF Attesta SHA2/AES based key derivation function (TBD)