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 is unencrypted and Aegis will try to parse 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 SHA-256 hash of the master key and a list of slots. The hash is used to verify the integrity of a decrypted slot. Note that this is meant for convenience, not as a security measure.

Length	Contents
32	uint8_t Master Key Hash
?	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
16	ID
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. The key derivation function is scrypt. The parameters used for scrypt are stored as additional data.

Length	Contents
4	uint32_t N
4	uint32_t r
4	uint32_t p
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.

{
    "version": 1,
    "counter": 10,
    "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",
        },
        ...
    ]
}