A vault is a file containing encrypted secrets. It is split into a header containing information about the encoding and cipher algorithm as well as a name (which is unencrypted). Vault identifiers are UUID v4.
The file format is designed to be easy to manipulate via random access seeking so that secrets can be inserted, updated and deleted efficiently.
In the header of a vault file is a summary which contains the vault name, identifier, cipher, and other information. It could be considered to be a pointer to a vault.
Some vaults are considered to be special and are marked with bit flags to indicate these properties, some examples:
- Default vault, the primary vault for an account
- Archive vault , archived secrets can be moved here
- Contacts vault, a vault just for contacts
- Authenticator, vault for 2FA secrets (TOTP)
An event log is an alternative representation of a vault which
is an append-only file for events, an in-memory merkle tree
keeps track of the commits to the event log.
The primary purpose of the event log is to allow efficient syncing of vaults between different devices.
Event logs can be reduced to a vault file and a vault file can be split into an event log.
Over time an event log may grow very large or the owner may wish to discard deleted and old versions of edited secrets so an event log can be compacted to a sequence of events that will match the data in the corresponding vault file but discard the history. The process of compaction rewrites the entire merkle tree for the event log so is a very destructive operation from the point of view of syncing between devices as the merkle trees on the different devices will have completely diverged.
If the password of a vault is changed the entire event log (and therefore merkle tree) needs to be rewritten.
In the case of compaction or a change in password for a vault great care must be taken to ensure the new data can be synced at the same time.
Assuming an event log has not been rewritten then it also allows an owner to time travel to an earlier point in the history and recover deleted or edited secrets.
See the sync docs for more information on event logs.
Folder is the term used to refer to the combined vault and event log files which represent the entirety of the data required for a collection of secrets.
The account signing key is an ECDSA (Secp256k1 curve) private key used to uniquely identify an account and verify account ownership by signing requests to a remote service.
An account address is an Ethereum-style address derived from the public key of the account signing key used to uniquely identify an account. An account address is used as the identifier so that remote servers (used for syncing data) can allow account creation and modification without requiring any sign-up which may expose personally identifiable information (PII) to the server.
The identity vault is a special kind of vault whose purpose is to protect the account signing key, provide a single password account sign in flow and to store delegated passwords. Delegated passwords are passwords for other folders managed by the account owner.
The primary password is the password used to unlock the identity vault granting access to an account.
The device vault contains the signing key that identifies a single device and a collection of other trusted devices.
A trusted device contains meta data about a device (operating system, hostname, hardware information etc) that allows the owner to easily identify the device and the public key of the device's signing key.
The device vault must never leave that device.
Device vaults are not included in backup archives, they are lazily created when an account owner signs in so after restoring from a backup archive a new device signing key would be created and the account owner would need to pair with other devices to add them to the collection of trusted devices again.
A cloud account refers to a paid subscription to a cloud-hosted syncing service.
A recovery group is a collection of participants that have been allocated shares in the private key used for social recovery. Members of a recovery group may or may not be subscribers to a cloud account.
A recovery pack is a mapping of vault identifiers (UUID v4) to the password for the corresponding vault. This is the map that will be encrypted during social recovery group creation.
The recovery pack must be encrypted using a secret only known to the account owner, afterwards it can be sent to a trusted third-party service for long-term storage.
The owner can then split the private key used to encrypt the recovery pack and distribute it to members of the recovery group.
The executor is a member of the recovery group that is authorized to perform the final decryption of the account owner's data.
See SOCIAL-RECOVERY.md for more information on the social recovery protocol.
Files can be internal (embedded in a folder) or external which encrypts the file data and stores it in a location determined by convention.
The convention for file storage is the vault identifier followed by the secret identifier and then the SHA256 hash of the encrypted file data.
Internal files are considered legacy and not recommended as they increase the size of folders and have negative performance implications.
Support for internal files may be removed in the future so use with caution.
User data is optional additional data that can be assigned to a secret, for example, a user might add a comment to the user data to give additional instructions to a recovery group on how to use a secret.
Custom fields are additional fields that can be assigned to the user data for a secret. They allow end users to manage additional data assigned to a secret adding flexibility to the shape of secret data.
Custom fields are implemented as nested secrets so whilst it is technically possible to nest custom fields it it not recommended.
It is possible to use any secret type for a custom field but that may be overwhelming from a user experience point of view so we recommend restricting the types available to custom fields, for example, limiting custom fields to notes, links, passwords and files gives a lot of flexibility without offering too many choices.
Some secret types such as Link and Password are intended to only be used in custom fields.
At the moment custom fields are not included in the search index, we may change this later.