VES End-To-End Encrypted Cloud Repository

There’s a single Master Vault associated with each VES user account. A Master Vault consists of a Primary Vault and an optional Shadow Vault. The Primary Vault is locked by the owner’s Primary VESkey. The main purpose of the Primary Vault is to store the App VESkeys to all the owner’s App Vaults, and the recovery tokens needed to provide VESrecovery assistance to the owner’s friends.

All items deposited into the Primary Vault are mirrored in the owner’s Shadow Vault, which will be used if and when the owner loses their Primary VESkey and initiates VESrecovery.

An App Domain is a namespace inside the VES repository. Each App Domain is identified by a non-empty ASCII string. The App Domain identifiers are case insensitive, i.e. both demo and Demo refer to the same App Domain.

Each App Domain is global to the VES repository, available to all VES users under the same identifier string.

App Domains having identifiers starting with x- or x. are considered experimental domain. Any VES API user can create a new experimental domain by simply creating a new App Vault that belongs to an experimental domain.

Non-experimental (production) App Domains are maintained by the VESvault team. The team can smoothly convert an experimental domain into a production domain upon request, as a part of an integration development cycle.

An External ID is an identifier of either an App Vault or a Vault Item. External ID is a non-empty case sensitive ASCII string unique within an App Domain namespace and the object type. For example Vault Items with external IDs test and Test within the App Domain my-domain are different objects, an App Vault with an external ID test or Test may also exist within the same App Domain.

Each App Domain may impose specific rules on creating and sharing App Vaults and Vault Items within this domain. Experimental domains are assigned the default rules:

• Any API user can create their own App Vault with an External ID that
  • matches the lowercase version of the User’s account email address,
  • or is non-empty and does not contain ‘@’ character
• Any API user can create an App Vault for another user with an External ID that matches the lowercase version of the vault owner’s email address
• Any API user can create a Vault Item within the domain namespace with an arbitrary non-empty External ID that does not include an ! character, and share the item with any other App Vaults, including App Vaults within other App Domain namespaces as long as the destination domain rules allow it.
• A Vault Item with an External ID containing ! can only be created by a user who is authorized with an App Vault with the matching domain, and the External ID exactly matching the part of the Vault Item External ID preceding the ! character, this is referred as a Private Vault Item.
• Any API user can share any Vault Items within other domain namespace with an experimental domain, as long as the source domain rules allow it.

Each instance of an object in VES repository has a numeric internal ID, a positive integer, assigned to it. An internal ID is unique within the object type. Unlike external IDs, internal IDs can be used to access internal objects and non-active instances – overwritten or deleted Vault Items, rekeyed or lost Vault Keys, internal Vault Items that store VESkeys and recovery tokens.

VES URI is a convenient way of referencing Vault Keys and Vault Items:

• ves:////user_email: reference a Master Vault for a specific VES user (note there are 4 slashes in fromt of the user_email).
• ves://domain/externalId/: reference an existing App Vault (note the / after the externalId).
• ves://domain/externalId/user_email: reference an App Vault. If the App Vault identified by domain and externalId doesn't exist – automatically create one for user_email. If the App Vault already exists – verify that it belongs to user_email.
• ves:///internalId/: reference a spacific Vault Key of any type by its internalId (note the / after the internalId).
• ves://domain/externalId: reference a Vault Item, an existing one or a new one (note there's no / after the externalId).
• ves:///internalId: reference a specific instance of a Vault Item by its internalId (note there's no / after the internalId).

The complete specifications of VES URI scheme can be found in this document.

App Vaults store custom end-to-end encrypted information specific to respective VES enabled apps. Each App Vault is locked by its own App VESkey.

The App VESkey is intended to be securely stored by the respective VES enabled app. A copy of the App VESkey is stored in the owner’s Primary Vault, and can be retrieved if the App is installed on a new device, has lost the stored VESkey, or has opted to not store the VESkey at all.

A Vault Key is an asymmetric encryption key, the private key being encrypted by a respective VESkey that unlocks this Vault Key.

When fully set up, each Vault has one active Vault Key associated with it. When the Vault Key is rekeyed, the former key changed status to “deleted”, and can be accessed by its internal ID for some time.

When a VES user shares a Vault Item with a recipient who doesn’t have a corresponding Vault set up, or doesn’t have a VES account at all, libVES creates a Temporary Vault Key for the recipient’s Vault. If other users share an item with the same recipient, a separate Temporary Vault Key is created by each user. Once the recipient has their corresponding Vault set up, the creator of each Temporary Vault Key can propagate the corresponding temporary VESkey to the recipient’s Vault, then the recipient can unlock and rekey the Temporary Vault Keys.

A Vault Item is an object in the VES repository that stores a block of data in an encrypted form. Each Vault Item has one or more Entries that store the content of the Vault Item encrypted with a respective Vault Key, belonging to a specific App Vault, Primary or Shadow Vault. Each associated Vault Key, when unlocked with its respective VESkey, can decrypt the content of the Vault Item from the respective Entry.

Thus, each Vault Item can be shared with a specific list of vaults, belonging to same or different VES users.

VES distinguishes between Internal Vault Items that are associated with Vault Keys, and User Vault Items associated with File Nodes.

Internal Vault Items are used to store App VESkeys, Temporary VESkeys and Recovery Tokens. Creating and sharing Internal Vault Items are subject to strict rules imposed by the VES API server. API users have limited control over Internal Vault Items.

User Vault Items are created and maintained by VES enabled apps, and are intended to be shared only among App Vaults. Each User Vault Item is identified by an App Domain and External ID, similarly to an App Vault. The namespace for Vault Items is separate from the namespace for App Vaults, so an App Vault and a User Vault Item with same App Domain and External Id may exist simultaneously.

When the content of a User Vault Item is replaced or deleted through the API, a new instance of the Vault Item is created with a new Internal ID. The previous version of the item and the associated entries are stored in VES repository for some time, and can be accessed by its old Internal ID.