Skip to content

Commit

Permalink
Update vault documentation
Browse files Browse the repository at this point in the history 
Here some changes to the vault documentation are made. The documentation
is updated to reflect the latest versions of both the vault and the
database, i.e. vault version 1 and database version 3.

Co-authored-by: Alexander Bakker <[email protected]>
  • Loading branch information
@Granddave @alexbakker
Granddave and alexbakker committed Mar 1, 2024
1 parent 224ec25 commit f91b6f0
Showing 1 changed file with 175 additions and 56 deletions.
231 changes: 175 additions & 56 deletions docs/vault.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,10 @@ format of the vault.
### Primitives

Two cryptographic primitives were selected for use in Aegis. An Authenticated
Encryption with Associated Data (AEAD) cipher and a Key Derivation Function
(KDF).
Encryption with Associated Data
([AEAD](https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data))
cipher and a Key Derivation Function
([KDF](https://en.wikipedia.org/wiki/Key_derivation_function)).

#### AEAD

Expand All @@ -36,15 +38,16 @@ This is a reasonable assumption to make, because it's highly unlikely that an
Aegis user will ever come close to saving the vault 2<sup>32</sup> times.

_Switching to a nonce misuse-resistant cipher like AES-GCM-SIV or a cipher with
a larger (192 bits) nonce like XChaCha-Poly1305 will be considered in the future._
a larger (192 bits) nonce like XChaCha-Poly1305 will be considered in the
future._

#### KDF

__scrypt__ is used as the KDF to derive a key from a user-provided password,
with the following parameters:
[__scrypt__](https://en.wikipedia.org/wiki/Scrypt) is used as the KDF to derive
a key from a user-provided password, with the following parameters:

| Parameter | Value |
| :-------- | :------------- |
| Parameter | Value |
|:----------|:---------------|
| N | 2<sup>15</sup> |
| r | 8 |
| p | 1 |
Expand Down Expand Up @@ -104,12 +107,17 @@ shown below:
}
```

It starts with a ``version`` number and a ``header``. If a backwards
incompatible change is introduced to the content format, the version number will
be incremented. The vault contents are stored under ``db``. Its value depends on
whether the vault is encrypted or not. If it is, the value is a string containing
the Base64 encoded (with padding) ciphertext of the vault contents. Otherwise,
the value is a JSON object.
It starts with a ``version`` number. If a forwards incompatible change is
introduced to the vault format, the version number will be incremented. The
current version of the vault format is ``1``.

The [``header``](#header), if not empty, contains the list of slots and the
encryption parameters used for decrypting the vault.

The vault contents are stored under ``db``. Its value depends on whether the
vault is encrypted or not. If it is, the value is a string containing the Base64
encoded (with padding) ciphertext of the vault contents. Otherwise, the value is
a JSON object. See [vault content](#vault-content) for details.

Full examples of a [plain text
vault](/app/src/test/resources/com/beemdevelopment/aegis/importers/aegis_plain.json)
Expand All @@ -122,9 +130,14 @@ password: [decrypt.py](/docs/decrypt.py).

### Header

The header starts with the list of ``slots``. It also has a ``params`` object
that holds the ``nonce`` and ``tag`` that were produced during encryption,
encoded as a hexadecimal string.
The header starts with the list of [``slots``](#slots-1). Each slot contains the
master key in an encrypted form together with the key wrapping parameters.

It also has a ``params`` object that holds the ``nonce`` and ``tag`` that were
produced during the AES-GCM encryption, encoded as a hexadecimal string. These
encryption parameters together with the master key (which can be retrieved by
decrypting the ``key`` from one of the slots) are used to decrypt the vault
contents found in the ``db`` field.

Setting ``slots`` and ``params`` to null indicates that the vault is not
encrypted and Aegis will try to parse it as such.
Expand All @@ -141,13 +154,13 @@ encrypted and Aegis will try to parse it as such.

#### Slots

The different slot types are identified with a numerical ID.
The different slot types are identified with a numerical ID.

| Type | ID |
| :---------- | :--- |
| Raw | 0x00 |
| Password | 0x01 |
| Biometric | 0x02 |
| Type | ID |
|:----------|:-----|
| Raw | 0x00 |
| Password | 0x01 |
| Biometric | 0x02 |

##### Raw

Expand Down Expand Up @@ -182,7 +195,7 @@ Raw slots don't imply use of a particular storage type.

As noted earlier, scrypt is used to derive a 256-bit key from a user-provided
password. A random 256-bit ``salt`` is generated and passed to scrypt to protect
against rainbow table attacks. Its stored along with the ``N``, ``r`` and ``p``
against rainbow table attacks. It's stored along with the ``N``, ``r`` and ``p``
parameters.

```json
Expand All @@ -201,56 +214,69 @@ parameters.
}
```

### Content
### Vault content

The content is a JSON object encoded in UTF-8.

```json
{
"version": 1,
"entries": []
"version": 3,
"entries": [],
"groups": []
}
```

It has a ``version`` number and a list of ``entries``. If a backwards
incompatible change is introduced to the content format, the version number will
be incremented.
It has a ``version`` number, a list of ``entries`` and a list of ``groups``. If
a forwards incompatible change is introduced to the content format, the version
number will be incremented. The current version of the vault content format is
``3``.

| Field | Type | Description |
|:------------|:------|:-----------------------------------------|
| ``version`` | int | The version of the vault content format. |
| ``entries`` | array | A list of [entries](#entries). |
| ``groups`` | array | A list of [groups](#groups). |

#### Entries

Each entry has a unique randomly generated ``UUID`` (version 4), as well as a
``name`` and ``issuer`` to identify the account name and service that the token
is for. Entries can also have an icon. These are JPEG's encoded in Base64 with
padding. The ``info`` object holds information specific to the OTP type. The
``secret`` is encoded in Base32 without padding.
Each entry has a unique randomly generated ``UUID``, as well as a ``name`` and
``issuer`` to identify the account name and service that the token is for.

There are a number of supported types:
Entries hold the following fields:

| Type | ID | Spec |
| :------------------ | :------- | :-------- |
| HOTP | "hotp" | [RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226)
| TOTP | "totp" | [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238)
| Steam | "steam" | N/A
| Yandex | "yandex" | N/A
| Field | Type | Description |
|:--------------|:---------------|:--------------------------------------------------------------------------------|
| ``type`` | string | The type of the OTP algorithm. See table below. |
| ``uuid`` | string | A UUID (version 4). |
| ``name`` | string | The account name. |
| ``issuer`` | string | The service that the token is for. |
| ``note`` | string | A personal note about the entry. |
| ``icon`` | string \| null | JPEG's encoded in Base64 with padding. |
| ``icon_mime`` | string \| null | The MIME type of the icon. Is null if ``icon`` is null. |
| ``icon_hash`` | string \| null | The SHA-256 hash of the icon. Is null if ``icon`` is null. |
| ``favorite`` | bool | Whether the entry is a favorite or not. |
| ``info`` | object | Information specific to the OTP type. |
| ``groups`` | array | A list of UUIDs of groups that the entry is a member of. See [Groups](#groups). |

There is no specification available for Steam's OTP algorithm. It's essentially
the same as TOTP, but it uses a different final encoding step. Aegis'
implementation of it can be found in
[crypto/otp/OTP.java](https://github.com/beemdevelopment/Aegis/blob/master/app/src/main/java/com/beemdevelopment/aegis/crypto/otp/OTP.java).
The ``info`` object contains different fields depending on the type of the OTP.

There is also no specification available for Yandex's OTP algorithm. Aegis'
implementation can be found in
[crypto/otp/YAOTP.java](https://github.com/beemdevelopment/Aegis/blob/master/app/src/main/java/com/beemdevelopment/aegis/crypto/otp/YAOTP.java)
There are a number of supported types:

The following algorithms are supported for HOTP and TOTP:
| Type | ID | Spec |
|:-------|:---------|:----------------------------------------------------------|
| HOTP | "hotp" | [RFC 4226](https://datatracker.ietf.org/doc/html/rfc4226) |
| TOTP | "totp" | [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) |
| Steam | "steam" | N/A |
| MOTP | "motp" | N/A |
| Yandex | "yandex" | N/A |

| Algorithm | ID |
| :-------- | :------- |
| SHA-1 | "SHA1" |
| SHA-256 | "SHA256" |
| SHA-512 | "SHA512" |
Common ``info`` fields for all types:

For Steam, only SHA-1 is supported. For Yandex, only SHA-256 is supported.
| Field | Type | Description |
|:-----------|:-------|:-----------------------------------|
| ``secret`` | string | The Base32 encoded secret. |
| ``algo`` | string | The hashing algorithm. |
| ``digits`` | int | The number of digits in the token. |

Example of a TOTP entry:

Expand All @@ -260,12 +286,105 @@ Example of a TOTP entry:
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Bob",
"issuer": "Google",
"note": "Main account",
"favorite": false,
"icon": null,
"icon_mime": null,
"icon_hash": null,
"info": {
"secret": "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
"algo": "SHA1",
"digits": 6,
"period": 30
}
},
"groups": [
"01234567-89ab-cdef-0123-456789abcdef"
]
}
```

##### HOTP and TOTP

TOTP uses the ``period`` field, which is the time step in seconds. HOTP uses the
``counter`` field, which is incremented every time a token is generated.

The following algorithms are supported for HOTP and TOTP:

| Algorithm | ID |
|:----------|:---------|
| SHA-1 | "SHA1" |
| SHA-256 | "SHA256" |
| SHA-512 | "SHA512" |

##### Steam

There is no specification available for Steam's OTP algorithm. It's essentially
the same as TOTP, but it uses a different final encoding step. Aegis'
implementation of it can be found in
[crypto/otp/OTP.java](/app/src/main/java/com/beemdevelopment/aegis/crypto/otp/OTP.java).

A couple of fields have fixed values:

| Field | Value |
|:-----------|:-------|
| ``algo`` | "SHA1" |
| ``period`` | 30 |
| ``digits`` | 5 |

##### MOTP

There is no specification available for MOTP. Aegis' implementation of it can be
found in
[crypto/otp/MOTP.java](/app/src/main/java/com/beemdevelopment/aegis/crypto/otp/MOTP.java).

A couple of fields have fixed values:

| Field | Value |
|:-----------|:------|
| ``algo`` | "MD5" |
| ``period`` | 10 |
| ``digits`` | 6 |

MOTP-specific fields:

| Field | Type | Description |
|:--------|:-------|:------------|
| ``pin`` | string | 4-digit PIN |

##### Yandex

There is no specification available for Yandex's OTP algorithm. Aegis'
implementation can be found in
[crypto/otp/YAOTP.java](/app/src/main/java/com/beemdevelopment/aegis/crypto/otp/YAOTP.java)

A couple of fields have fixed values:

| Field | Value |
|:-----------|:---------|
| ``algo`` | "SHA256" |
| ``period`` | 30 |
| ``digits`` | 8 |

Yandex-specific fields:

| Field | Type | Description |
|:--------|:-------|:---------------|
| ``pin`` | string | 4-16 digit PIN |

#### Groups

A group consists of a ``name`` and a randomly generated ``uuid`` (version 4).

| Field | Type | Description |
|:---------|:-------|:-----------------------|
| ``uuid`` | string | A UUID (version 4). |
| ``name`` | string | The name of the group. |

Example:

```json
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"name": "Personal"
}
```

0 comments on commit f91b6f0

Please sign in to comment.