Resource

Description

Resource is the basic unit for data encryption/decryption during E2EE communications.

A resource allows to share (encrypt) and access shared (decrypt) data. To encrypt data an identity — the creator — creates a new or reuses an existing resource. A resource is typically reused when multiple chunks of data of the same nature are encrypted, see the examples for details.

An identity decrypts data with the same resource that was used for encryption.

As with identities each resource has a sharing group associated with it. A sharing group is a list of identities — sharers — that can use the resource to encrypt/decrypt data. The sharing group is defined during the resource creation; sharers can extend it afterwards. Only sharers can use the resource. The creator of a resource is not automatically included in the resource's sharing group.

The creator can delete the resource.

Creating a resource

An identity can create a resource:

let resourceKind = "img/jpg"
let resourcePayload = { description: "My rabbit's photo" }
let resourceSharers = [alice.login, bob.login]
let aliceResource = await new DataPeps.ResourceAPI(aliceSession).create(
  resourceType,
  resourcePayload,
  resourceSharers
)

Here Alice and Bob are the resource's sharing group.

Alice uses resourceKind to specify the type of data encrypted with the resource. resourcePayload is used as a free format object that contains the resource's meta data, that Alice considers significant.

By default the resource payload is stored as a JSON object. An identity can change the format of the resource's payload by passing a serialization function during resource creation:

let payloadToStringFunction = (payload => {
  // code to serialize the payload
})
let aliceResource = await aliceSession.Resource.create(
  resourceType,
  resourcePayload,
  ["alice", "bob"],
  options: { serialize: payloadToStringFunction }
)

Getting a resource

The resource creator or a sharer can get the resource with the use of the resource's ID:

let aliceResource = await new DataPeps.ResourceAPI(bobSession).get(aliceResourceId)

By default, the resource payload is assumed to be in JSON. If it is not the case, a sharer should specify a function for extracting the payload when getting a resource:

let payloadFromStringFunction = (payload => {
  // code to deserialize the payload
})
let bobResource = await new DataPeps.ResourceAPI(bobSession).get(aliceResourceId, options: { parse: payloadFromStringFunction })

Using a resource

Resources are used for data encryption/decryption. Resources are managed by DataPeps; processed data, on the contrary, does not make part of the DataPeps infrastructure, thus it is managed (stored, exchanged, etc.) by identities.

An identity encrypts the data like this:

let photo = readFile("rabbit.jpg")
let encryptedPhoto = aliceResource.encrypt(photo)

Now, to share the photo with Bob, Alice relays to Bob the encrypted photo and the ID of the resource used:

let resourceId = aliceResource.id
await sendToBob([resourceId, encryptedPhoto])

When Bob wants to access the photo, he gets the resource from DataPeps with the use of the resource's ID and decrypts the photo:

let aliceResource = await new DataPeps.ResourceAPI(bobSession).get(resourceId)
let photo = aliceResource.decrypt(encryptedPhoto)

To get the resource Bob must be the resource's creator or a resource's sharer.

Reusing a resource

An identity can reuse an existing resource to encrypt/decrypt multiple files. To do this an identity gets the resource from DataPeps with the use of the resource's ID:

let anotherPhoto = readFile("dormouse.jpg")
let aliceResource = await new DataPeps.ResourceAPI(aliceSession).get(resourceId)
let encryptedPhoto = aliceResource.encrypt(anotherPhoto)

let bobResource = await new DataPeps.ResourceAPI(bobSession).get(resourceId)
let decryptedPhoto = bobResource.decrypt(encryptedPhoto)

Sharing a resource

An identity from the resource's sharing group can extend the group:

await new DataPeps.ResourceAPI(bobSession).extendSharingGroup(resourceId, ["charlie"])

Deleting a resource

A resource can be hard- or soft-deleted.

After a hard delete the resource is destroyed and cannot be reused. Only the creator can hard-delete a resource:

// after executing the following line, the resource is wiped from DataPeps
await new DataPeps.ResourceAPI(aliceSession).delete(resourceId)

Any sharer can soft-delete (we also use the term "unlink") a resource. When a sharer soft-deletes the resource, the sharer is removed from the resource's sharing group; the rest of the sharers can access the resource as before.

A resource is soft-deleted like this:

// after executing the following line, the sharing group of the resource is deleted, the resource can be reused
await  new DataPeps.ResourceAPI(aliceSession).unlink(resourceId)

Examples

Sending a message — resource creating, getting and using.

Deleting a resource — deleting a resource.