Aegis/doc/db.md

# Database

The database is encoded in a simple binary format with JSON content at its core.

## Encryption

The content of the database can be encrypted with AES in GCM mode. The nonce and
authentication tag are stored in the plain section of this file.

If there is no Slots and/or EncryptionParameters section in the file, it is
implied that the content of is unencrypted and Aegis will try to interpret it as
such.

## Format

The file format starts with a small header that contains some magic and a
version number. A list of sections follows. These sections contain some
information needed to perform decryption of the database. The (encrypted)
content of the database starts after the end marker section.

All integers are encoded in Little Endian.

### Header

| Length | Contents                 |
|:-------|:-------------------------|
| `5`    | "AEGIS" encoded in ASCII |
| `1`    | `uint8_t` Version        |
| `?`    | List of sections         |
| `?`    | Content                  |

### Sections

| Length | Contents          |
|:-------|:------------------|
| `1`    | `uint8_t` ID      |
| `4`    | `uint32_t` Length |
| `?`    | Section data      |

ID can be one of:

| Value  | Name                 |
|:-------|:---------------------|
| `0x00` | EncryptionParameters |
| `0x01` | Slots                |
| `0xFF` | End marker           |

#### EncryptionParameters

| Length | Contents |
|:-------|:---------|
| `12`   | Nonce    |
| `16`   | Tag      |

#### Slots

This section contains a list of slots. All slots contain the master key
encrypted with raw AES. The key that is used for encryption depends on the slot
type.

A slot has the following structure.

| Length | Contents            |
|:-------|:--------------------|
| `1`    | `uint8_t` Type      |
| `32`   | Encrypted key       |
| `?`    | Additional data     |

Type can be one of:

| Value  | Name        |
|:-------|:------------|
| `0x00` | Raw         |
| `0x01` | Password    |
| `0x02` | Fingerprint |

##### Raw

This slot type contains no additional data.

##### Password

With this slot type the key used for the master key encryption is derived from a
user-provided password using PBKDF2 with SHA1 (should be changed to SHA256
before initial release) as the underlying PRF. The parameters used for PBKDF2
are stored as additional data.

| Length | Contents                        |
|:-------|:--------------------------------|
| `8`    | `uint64_t` Number of iterations |
| `32`   | Salt                            |

##### Fingerprint

A fingerprint slot is exactly the same as a Raw slot.

#### End marker

This section indicates the end of the list of sections. This section doesn't
have any content and thus its length is 0.

### Content

The content of the database is a JSON file encoded in UTF-8.

```json
{
    "version": 1,
    "entries":
    [
        {
            "id": 1,
            "name": "ACME Co/john@example.com",
            "url": "otpauth://totp/ACME%20Co:john@example.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30",
            "order": 0,
        },
        ...
    ]
}
```