Decryptor

Post data request

POST /data-requests

Description

Decryptor requests encryptor's data by posting a data request to the ledger through this endpoint. After sufficient number of trustees and validators observe the data request and have responded to it, the decryptor will be able to decrypt the secret.

Parameters

Name
In
Type
Required
Description
-
body
true
none
Example
{
"token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}

Responses

Status
Meaning
Description
Schema
200
OK
Succeeded
400
Bad Request
Invalid token
401
API key is missing or invalid
409
Conflict
Conflict

200 OK

The data request is successfully posted on the ledger.
Example
{
"ok": true,
"message": "Successfully posted data request",
}

400 Bad Request

Input is malformed. Check that:
  • token is a string
  • token is a 128-bit hex string
Example 1
{
"ok": false,
"message": "Wrong type at body.token",
}
Example 2
{
"ok": false,
"message": "wrong length at body.token. Expected: 32; given: 64",
}

401 Unauthorized

API key is missing or incorrect.
Example
{
"ok": false,
"message": "Unauthorized",
}

409 Conflict

The data request has already been posted.
Example
{
"ok": false,
"message": "Data request has been posted before",
}

Get ciphertext

GET /encryptions/{token-hash}/ciphertext

Description

Retrieve the ciphertext part of an Encryption. After decrypting it with decryptor's decryption key, one should find a payload encrypted with a symmetric key together with a digital signature by the encryptor. The decryptor will not have sufficient information to further decrypt unless there are anough trustees and validators who have responded to the data request. See the code samples to see how decryptions are done.

Parameters

Name
In
Type
Required
Description
token-hash
path
Sha256
true
Hash value of the token
Example
GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/ciphertext

Responses

Status
Meaning
Description
Schema
200
OK
Succeeded
Inline
401
API key is missing or invalid
404
Not found
Encryption not found

200 OK

Successfully retrieved the ciphertext from the encryption.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
ciphertext
true
none
none
Example
{
"ok": true,
"ciphertext": {
"encryptedMessage": {
"ciphertext": "base64_encoded_data",
"iv": "base64_encoded_data",
},
"encryptedEphemeralKey": "base64_encoded_data",
},
}

401 Unauthorized

API key is missing or incorrect.
Example
{
"ok": false,
"message": "Unauthorized",
}

404 Not found

The encryption does not exist.
Example
{
"ok": false,
"message": "Encryption with token hash d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4 not found",
}

Get trustee responses

GET /data-requests/{token}/trustee-responses

Description

Retrieves all trustee responses for a data request signed by the corresponding Trustee. Sufficient number of individual trustees' responses reconstruct to a masked symmetric key. See code samples for details.
Note 1: The path parameter is the token which should be kept secret until the data request related to the token has been posted. Therefore, this endpoint should be called only after the data request is posted onto the ledger.
Note 2: This endpoint returns successful status even if not enough trustees have responded. User should check if the number of responses is at least the secret sharing threshold before attempting to reconstruct the secret. Otherwise a garbage value will be reconstructed.

Parameters

Name
In
Type
Required
Description
token
body
Token
true
none
Example
GET /data-requests/{token}/trustee-responses

Responses

Status
Meaning
Description
Schema
200
OK
Succeeded
Inline
400
Bad Request
Token is invalid in format
401
API key is missing or invalid
404
Not found
Encryption not found

200 OK

Successfully retrieved trustee responses for a data request.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
trusteeResponses
true
none
none
Example
{
"ok": true,
"trusteeResponses": {
"trustee1": {
"trusteeResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"trusteeShare\":\"Ad8WqKbFL3ft1cCRYJE8Yh2Tb6UqbEVfErg/RF5RoXQA\",\"type\":\"trustee_response\",\"trusteeId\":\"trustee1\"}",
"signature": {
"signerMetdata": {
"id": "trustee1",
"fullName": "Trustee-1",
"role": "Trustee",
},
},
},
},
}

400 Bad Request

Request is malformed.
Example
{
"ok": false,
"message": "wrong length at path.token. Expected: 32; given 31",
}

401 Unauthorized

API key is missing or incorrect.
Example
{
"ok": false,
"message": "Unauthorized",
}

404 Not found

The data request does not exist.
Example
{
"ok": false,
"message": "Data request not found",
}

Get validator responses

GET /data-requests/{token}/validator-responses

Description

Retrieves all validator responses for a data request signed by the corresponding Validator. Sufficient number of individual validators' responses reconstruct to a mask that together with trustees' responses reveals a symmetric key. The combined results also reveals the decryptor's identity. See code samples
Note 1: The path parameter is the token which should be kept secret until the data request related to the token has been posted. Therefore, this endpoint should be called only after the data request is posted onto the ledger.
Note 2: This endpoint returns successful status even if not enough validators have responded. User should check if the number of responses is at least the secret sharing threshold before attempting to reconstruct the secret. Otherwise a garbage value will be reconstructed.

Parameters

Name
In
Type
Required
Description
token
body
Token
true
none
Example
GET /data-requests/{token}/validator-responses

Responses

Status
Meaning
Description
Schema
200
OK
Succeeded
Inline
400
Bad Request
Token is invalid in format
401
API key is missing or invalid
404
Not found
Encryption not found

200 OK

Successfully retrieved validator responses for a data request.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
validatorResponses
true
none
none
Example
{
"ok": true,
"validatorResponses": {
"validator1": {
"validatorResponse": ,
"signature": {
"signerMetdata": {
"id": "validator1",
"fullName": "Validator-1",
"role": "Validator",
},
},
},
},
}

400 Bad Request

Request is malformed.
Example
{
"ok": false,
"message": "wrong length at path.token. Expected: 32; given 31",
}

401 Unauthorized

API key is missing or incorrect.
Example
{
"ok": false,
"message": "Unauthorized",
}

404 Not found

The data request does not exist.
Example
{
"ok": false,
"message": "Data request not found",
}

Schemas

DataRequest

A data request, containing a token whose hash value was provided by the encryptor at encryption time.
Example
{
"token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}

Schema

Name
Type
Required
Restrictions
Description
token
Token
true
none
none

Ciphertext

A piece of asymmetrically encrypted ciphertext. It is created by first generating a symmetric ephemeral key, encrypt symmetrically the message using the ephemeral key, then encrypt asymmetrically the ephemeral key by an encryption key. All binary data are encoded in base64. For details, read the code samples.
Example
{
"encryptedMessage": {
"ciphertext": "base64_encoded_data=",
"iv": "base64_encoded_data="
},
"encryptedEphemeralKey": "base64_encoded_data=",
}

Schema

Name
Type
Required
Restrictions
Description
encryptedMessage
object
true
none
Cipher of a message encrypted with an ephemeral key
» ciphertext
Base64
true
none
none
» iv
Base64
true
none
none
encryptedEphemeralKey
Base64
true
none
The ephemeral key encrypted by an asymmetric encryption key

Base64

A base64-encoded binary data.
Example
"aGVsbG8gd29ybGQ="

Schema

Type
Restrictions
string
none

Token

A 128-bit random string kept secret between the encryptor and decryptor after encryption stage and before data request stage. It identifies a data request. Its hash value identifies an encryption. The decryptor posts it on the ledger at data request stage.
Example
"0fe5ff17c6ee6efa8ca385587b1e1ac2"

Schema

Type
Restrictions
string
/[0-9a-fA-Z]{32}/

Sha256

A Sha256 hash value as a hexidecimal string.
Example
"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"

Schema

Type
Restrictions
string
/[0-9a-fA-F]{64}/

TrusteeId

ID of a trustee. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
my_trustee-1

Schema

Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}

ValidatorId

ID of a validator. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.

Example

my_validator-2

Schema

Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}

ApiResponse

Example
{
"ok": true,
"message": "string"
}

Schema

Name
Type
Required
Description
ok
boolean
true
The request is successful or not
message
string
true
none

TrusteeResponse

A trustee response to a data request. It contains the decrypted trustee share for the decryptor to perform a full decryption on a secret. It also consists of metadata for identifying the corresponding data request.
Example
{
"padName": "my-pad-1.0",
"token": "e3b0c44298fc1c149afbf4c8996fb924",
"trusteeShare": "0110",
"type": "trustee_response",
"trusteeId": "trustee1",
}

Schema

Name
Type
Required
Restrictions
Description
padName
PadName
true
none
The instance where the data request is posted
token
Token
true
none
The ID of the data request
trusteeShare
Base64
true
none
The decrypted trustee share
type
enum
true
none
Type of response
trusteeId
TrusteeId
true
none
ID of the responding trustee

Enumerated Values

Property
Value
type
"trustee_response"

SignedTrusteeResponse

A trustee response attached with a digital signature for everyone to validate the response's integrity.
Note that the trustee response is represented as a string (instead of an object). This ensures that there is a unified way to verify the signature.
Example
{
"trusteeResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"trusteeShare\":\"0110\",\"type\":\"trustee_response\",\"trusteeId\":\"trustee1\"}",
"signature": {
"signerMetadata": {
"id": "trustee1",
"fullName": "Trustee-1",
"role": "Trustee"
},
"payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
},
}

Schema

Name
Type
Required
Description
trusteeResponse
true
none
signature
Signature
true
none

Signature

A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.
Schema
{
"signerMetadata": {
"id": "string",
"fullName": "string",
"role": "Trustee",
},
"payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ==",
}

Schema

Name
Type
Required
Description
signerMetadata
false
none
payload
Base64
false
none

Participant

Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.
Example
{
"id": "my_trustee-1",
"fullName": "Trustee-1",
"role": "Trustee"
}

Schema

Name
Type
Required
Description
id
true
/[0-9a-zA-Z-_]{3,30}/
fullName
string
true
/Trustee-[0-9a-zA-Z_]+/ or /Validator-[0-9a-zA-Z_]+/
role
enum
true
none

Enumerated Values

Property
Value
role
Trustee
role
Validator
role
Server
Last modified 8mo ago