Encryption API

Endpoint	Method	Description
encryption:createEpoch	websocket	Create encryption epoch
encryption:updateEpoch	websocket	Update encryption epoch
encryption:listEpoches	websocket	List encryption epoches
encryption:listEpochesByTuples	websocket	List encryption epoches by tuples
encryption:listEpochesByZAddress	websocket	List encryption epoches by z address
encryption:getLastEpoch	websocket	Get last encryption epoch
encryption:getEpochChain	websocket	Get encryption epoch chain
encryption:onEpochCreated	websocketEvent	On encryption epoch created event

Create encryption epoch

Method: websocket

Endpoint: encryption:createEpoch

Description: Api creates new epoch for target item encryption. Epoch initiator should create viewing key and encrypt it for zAddresses of each owner.

Encryption owner could be:

1. User - keys are encrypted to user zAddress.
2. Another item in the system (like room or directory) - keys are encrypted to item zAddress and could be decrypted using encryption keychain.

Only users who have viewing key for that epoch (or to keychain root) will be able to decrypt cypher data.

Request:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "targetZAddress": string  // zAddress of encryption target for current epoch
        "targetType": string  // type of encryption target, like 'channel' or 'resource'
        "ownerKeys": [{  // viewing keys for epoch
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
        "expectedEpoch": int  // optional, if provided - server will check that new epoch equals to expectedEpoch (detect simultaneous epoch creation)
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoch": {
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Update encryption epoch

Method: websocket

Endpoint: encryption:updateEpoch

Description: Api updates encryption epoch for owner. This is useful in case when user has changed his zAddress and wants to update viewing keys correspondingly.

Request:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "epoch": int  // encryption epoch to update
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches

Method: websocket

Endpoint: encryption:listEpoches

Description: Api returns latest encryption epoches (with owner context) for provided targetId.

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "targetId": string  // encryption target id, like channelId or resourceId
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches by tuples

Method: websocket

Endpoint: encryption:listEpochesByTuples

Description: Api returns encryption epoches (with owner context) for provided targetId-epoch tuples.

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "epochTuples": [ ( targetId string, epoch int ) ]  // list of [targetId, epoch] tuples to fetch
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches by z address

Method: websocket

Endpoint: encryption:listEpochesByZAddress

Description: Api returns encryption epoches (with owner context) for provided owner zAddress.

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

Get last encryption epoch

Method: websocket

Endpoint: encryption:getLastEpoch

Description: Api returns last encryption epoch for provided targetId.

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "targetId": string  // encryption target id, like channelId or resourceId
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoch": {
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

Get encryption epoch chain

Method: websocket

Endpoint: encryption:getEpochChain

Description: Api returns list of epoches by provided tuples + parent epoches that are required to build encryption context chain.

Request:

{
    "data": {
        "epochTuples": [ ( targetId string, epoch int ) ]  // list of [targetId, epoch] tuples
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

On encryption epoch created event

Event: encryption:onEpochCreated

Description: Event is triggered when new epoch is created.

Data:

{
    "data": {
        "epochKey": string  // epoch:targetId
        "targetId": string  // encryption target id, like channelId or resourceId
        "targetZAddress": string  // zAddress of encryption target for current epoch
        "targetType": string  // type of encryption target, like 'channel' or 'resource'
        "epoch": int  // encryption epoch number
        "created": timestamp  // epoch creation time
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "error": { "status": bool, "code": int, "message": string }
}