aes/SPEC.md

blek! AES 1.0 standart draft

PREAMBLE

This standart does not describe an encryption algorithm; It is a way to store encrypted AES data.

NOTATIONS AND CONVENTIONS

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are interpreted as described in BCP 14 RFC2119 RFC8174

This document also uses the following terminology:

Name	Description
SHA256(x)	An x value hashed via the SHA256 hashing function.
base64	The base64 data encoding format, which is described in RFC4648

NAMING

This section is more of a convention rather than a requirement.

blek! AES can be written as baes or b-aes, non-case sensitive.

Recommendations for implementations:

1. Name the blek! AES class or namespace bAes, b_aes, BAes, B_AES in camel case, snake case, pascal case and constant case.
2. If the implementation is in a function based language like C, prefix the functions with baes_.

1. File format

The file is a serialized array of strings encoded with either JSON or CBOR. The filename MUST end with either .json or .cbor extension to clarify the encoding. If there is no filename available in a specific context (like a multipart form), it MUST be indicated via something else, like HTTP's Content-Type header. See 3. Filename for more details.

2. Structure of the file

The file MUST follow this schema:

[
    0, // blek! AES version - 0
    "CBC", // AES mode - either CBC or ECB
    "IV", // in base64 format
    "encrypted payload in base64 format",
    "argon2id", // passphrase hashing format - either argon2, argon2i, argon2d, argon2id or sha256
    "hashed passphrase",
    128 // 128, 192 or 256 bits
]

2.x paragraphs explain each element by index.

2.1 blek! AES version

This field must be 0 (a JSON integer).

2.2 AES mode

This field specifies the mode of the AES algorithm. For now it is limited to CBC and ECB only. See AES spec for more info.

2.3 IV

This field specified a base64 encoded IV value of the algorithm. See AES spec for more info.

2.4 Payload

The encrypted data encoded with base64, which is specified in RFC4648.

2.5 Passphrase hashing format

It can be either any version of argon2 (RFC9106) or SHA256. The latter is included only to support older systems, which means it is not recommended to use it.

2.6 Hashed passphrase

The passphrase hashed using a hashing function defined in 2.5.

If the hashing function is any version of argon2, it must be encoded according to the argon2 encoding format (proper specification needed).

If the hashing function is SHA256, it must be encoded using hexadecimal characters, like that: SHA256(123) = a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3. A-F characters may or may not be uppercase.

2.7 Length of the passphrase

MAY be one of: 128, 192 or 256.

This field indicates the length of the passphrase according to the AES specification.

3. Filename

A file MUST be named according to this format: (The file name).baes.(either json or cbor), so that message.baes.json and message.baes.cbor would be valid filenames for the blek! AES format.

If there is no filename available in a specific context (such as an HTTP multipart form), other indicators MAY be used to tell if the file is a blek!AES file:

1. Content-Type header must be either application/x-blekaes-json or application/x-blekaes-cbor
2. The file is a JSON/CBOR encoded array of 7 elements, where the first element is always 0 (a JSON integer), and all other elements are strings, except for the last one which is an integer and can be one of the following values: 128, 192 or 256.

4. Example of a file

A simple example would be:

[
    0,
    "CBC",
    "MTIzNDU2NzgxMjM0NTY3OA==",
    "xErdsgF1ejfkHf3abyFGt/dGL5YqucJ4OQ/JCUiaTZJMCbvFoYTwQnCi8bbPfsvT",
    "SHA256",
    "33cdbc3872b3789776eff6178cd7585d9c9b080c752aa4e92c274d768e2a7ea2",
    128
]

This example in CBOR format would be (base64-encoded):

hwBjQ0JDeBhNVEl6TkRVMk56Z3hNak0wTlRZM09BPT14QHhFcmRzZ0YxZWpma0hmM2FieUZHdC9kR0w1WXF1Y0o0T1EvSkNVaWFUWkpNQ2J2Rm9ZVHdRbkNpOGJiUGZzdlRmU0hBMjU2eEAzM2NkYmMzODcyYjM3ODk3NzZlZmY2MTc4Y2Q3NTg1ZDljOWIwODBjNzUyYWE0ZTkyYzI3NGQ3NjhlMmE3ZWEyGIA=

The passphrase is 1234567812345678.