# 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](https://www.rfc-editor.org/info/rfc2119) [RFC8174](https://www.rfc-editor.org/info/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](https://www.rfc-editor.org/rfc/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 a MIME type.
See [3. Filename](#3-filename) for more details.

# 1.1 MIME type
One of two are allowed to be used as a MIME type: `application/x-blekaes-json` or `application/x-blekaes-cbor`.

# 2. Structure of the file
The file MUST follow this schema:

```js
[
    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](https://www.rfc-editor.org/rfc/rfc4648).

## 2.5 Passphrase hashing format
It can be either any version of argon2 ([RFC9106](https://www.rfc-editor.org/rfc/rfc9106.html)) 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](#25-passphrase-hashing-format).

If the hashing function is any version of argon2, it must be encoded according to the [argon2 encoding format](https://github.com/P-H-C/phc-winner-argon2/blob/master/src/encoding.c#L240) (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. MIME type 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:

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

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

The passphrase is `1234567812345678`.