VESvault End-To-End Encrypted Repository

VESvault Repository Diagram
The diagram below represents a realistic example of VESvault repository. The diagram includes
  • 2 user items stored in VES – ves://app1/item1 and ves://app2/item1 – shared among several users,
  • Temporary vault keys in vaious stages of key exchange
  • Shadow Vault keys, VESrecovery, and partially provided assistance
The relationships among Users, Vault Keys and Vault Items are explained in the further sections.

Master Vault ves:////alice@example.com
currentves:///109/
shadowves:///110/
lostves:///103/
recoveryves:///104/
App Vault ves://app1/alice@example.com/
secondaryves:///111/
lostves:///106/
App Vault ves://app1/alice2/
secondaryves:///107/
Internal: VESkey to ves:///105/
ves:///102
Internal: VESkey to ves:///106/
ves:///105
Data: ves://app1/item1
ves:///107
ves:///106
Internal: VESkey to ves:///107/
ves:///108
Internal: VESkey to ves:///111/
ves:///114
Internal: VESrecovery Token #1 to ves:///112/
ves:///115
App Vault ves://app2/bob@example.com/
secondaryves:///108/
App Vault ves://app1/bob@example.com/
tempves:///114/ Bob
tempves:///116/ Alice
Internal: VESrecovery Token #1 to ves:///104/
ves:///101
Internal: VESkey to ves:///108/
ves:///109
Data: ves://app2/item1
ves:///110
Internal: VESrecovery Token #1 to ves:///110/
ves:///111
Internal: VESkey to ves:///113/
ves:///116
Internal: VESkey to ves:///114/
ves:///118
Internal: VESkey to ves:///115/
ves:///119
Internal: VESkey to ves:///116/
ves:///120
Master Vault ves:////cindy@example.com
tempves:///105/ Alice
tempves:///113/ Bob
Internal: VESrecovery Token #2 to ves:///104/
ves:///103
Internal: VESrecovery Token #2 to ves:///110/
ves:///112
Internal: VESrecovery Token #2 to ves:///112/
ves:///117
Master Vault ves:////dave@example.com
currentves:///102/
Internal: VESrecovery Token #3 to ves:///104/
ves:///104
Internal: VESrecovery Token #3 to ves:///110/
ves:///113
App Vault ves://app2/emma@example.com/
tempves:///115/ Bob
Master Vaults
There’s a single Master Vault associated with each VESvault 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.
App Domains and External IDs
An App Domain is a namespace inside the VESvault 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 VESvault repository, available to all VESvault users under the same identifier string.
App Domains having identifiers starting with x- or x. are considered experimental domain. Any VESvault 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 imposes 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 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.
  • Any API user can share Vault Items within other domain namespace with an experimental domain, as long as the source domain rules allow it.
Internal IDs
Each instance of an object in VESvault 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 URIs
VES URI is a convenient way of referencing Vault Keys and Vault Items:
  • ves:////user_email: reference a Master Vault for a specific VESvault 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
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.
Vault Keys
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 VESvault user shares a Vault Item with a recipient who doesn’t have a corresponding Vault set up, or doesn’t have a VESvault 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.
Vault Items
A Vault Item is an object in the VESvault 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 VESvault users.
VESvault 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 VESvault repository for some time, and can be accessed by its old Internal ID.