114 lines
5.2 KiB
Markdown
114 lines
5.2 KiB
Markdown
# blek! AES 1.0 standart draft
|
|
This document describes a file standart for storing AES-encrypted data, and requests discussion and suggestions for improvements.
|
|
|
|
This document is not an RFC and does not have any relations with the Internet Engineering Task Force.
|
|
|
|
# ABSTRACT
|
|
blek! AES is an array of elements which is encoded with either CBOR or JSON.
|
|
|
|
# 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) |
|
|
| MIME type | The MIME file type, as described in [RFC2045](https://www.rfc-editor.org/rfc/rfc2045) |
|
|
| AES | The Advanced Encryption Standart, as described in [RFC3826](https://www.rfc-editor.org/rfc/rfc3826) |
|
|
| argon2 | The argon2 hashing algorithm, as described in [RFC9106](https://www.rfc-editor.org/rfc/rfc9106.html)
|
|
|
|
# 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 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`.
|
|
|