When a client instance is started for the very first time, a number of things have to setup first to allow creating a EDV at a provider:

1. A master key has to be setup. For human-facing clients, this key is derived from a master passphrase. This symmetric master key will be used to encrypt all data-at-rest of the client instance.

2. A session is created. This session is initialized with a new Ed255191 based EdDSA public-private key-pair for requests to services and EDVs, and authorization with ZCaps.

3. This key is used to create the session DID - also known as "controller DID".

4. The controller DID is used to request a new EDV at a chosen provider. The request contains data about the client, most importantly the did:key.

5. The key receives the initial capability delegation from the root of trust. Several attributes are generated (e.g. IDs, sets up a did:key for the EDV) for the EDV.

When uploading a document, the users client will store a file key to the encrypted file index, chunk the file (explained below) and encrypt the chunks with the file key.

Encrypted search

1. The underlying encrypted search implementation parses the document structure (depending on file format, e.g. JSON, XML, etc.)

2. and creates a list of keywords that were found in the file. This is the search index for this file.

3. It gets encrypted with the encrypted search key. This is the encrypted index.

Chunking

1. The document is split into chunks. Chunks may not have a size exceeding the maximum of 1 MiB each. This is restricted per the Confidential Storage specification document.

2. Each chunk is individually encrypted with authenticated encryption using a file key.

3. An index (Resource Structure) is created, which is used to be able to recreate the file from the individual chunks later on. It gets encrypted, then being the encrypted chunk index (Encrypted Resource Structure).

Chunk transmission to the EDV

1. The encrypted chunks are sent to the EDV using individual request authorizations using ZCaps.

2. The encrypted chunk index and encrypted search index get stored in the EDV (each also being authorized using ZCap capability invocations).

A client supports multiple EDV-groupings by utilizing a session-based storage container. It will be referred to simply as "session" hereafter.

Such a session consists of a unique identifier, key identifier, Decentralized Identifier (DID), list of EDV metadata as required to interact with the respective EDVs. EDV metadata consists of the EDV identifier, server URL, root delegation (from the EDV DID to the client’s DID) and an index key:

This container is not explicitly defined in the specifications, and was chosen to allow users to easy import and export of all relevant data to multiple of their devices.

Note that this container as a whole can be exported from a client and imported into other clients, allowing users to easily access their connected EDVs on multiple devices. To do so, the session will be encoded as JSON and encrypted to a JWT, using the clients master passphrase as the symmetric key.

When uploading a document, the users client will store a file key to the encrypted file index, chunk the file (explained below) and encrypt the chunks with the file key:

Client data request from services

1. The service transmits a request to the client, indicating a context, desired data type, and it’s did:key (for the services public key).

2. Assuming the client accepts the request, it queries the document index for the list of required chunks (in correct order), and responds with a delegated ZCap authorization for each of the specific chunks, bundled with the file key.

Sequence Diagram illustrating service access:

Data exchange between service and EDV

1. The service contacts the EDV with a object retrieval request for each of the required file chunks. The requests are accompanied with the ZCap capability invocation the client delegated to the service.

2. The EDV encrypts the requested objects with the public key of the delegated did:key in the ZCap capability invocation and answers them back to the service.

Note that, both of steps may happen in parallel.

Service data decryption

1. The service decrypts each of the individually EDV-encrypted chunks with their private key.

2. The service decrypts each of the individually client-encrypted chunks using the file key provided by the client.

3. The service puts the chunks in the order specified by the client response.

Revocation

The client may revoke the data access of a previously shared(/trusted) service at any time using one of two possible methods:

• The client indicates a caveat in the initial ZCap capability delegation to the service, e.g. using SimpleCredentialStatus2022, which accesses a trusted revocation service. Multiple of such may be defined.

• The client uses the inbuilt did:key revocation feature of the EDV, which works like a blacklist, indicating otherwise valid ZCap authorizations for specific did:key ids no longer valid.