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	DataRequest	true	none

Example

{
  "token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}

Responses

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

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	Unauthorized	API key is missing or invalid	ApiResponse
404	Not found	Encryption not found	ApiResponse

200 OK

Successfully retrieved the ciphertext from the encryption.

Schema

Name	Type	Required	Restrictions	Description
ok	boolean	true	none	none
ciphertext	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	ApiResponse
401	Unauthorized	API key is missing or invalid	ApiResponse
404	Not found	Encryption not found	ApiResponse

200 OK

Successfully retrieved trustee responses for a data request.

Schema

Name	Type	Required	Restrictions	Description
ok	boolean	true	none	none
trusteeResponses	dict<TrusteeId, SignedTrusteeResponse>	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	ApiResponse
401	Unauthorized	API key is missing or invalid	ApiResponse
404	Not found	Encryption not found	ApiResponse

200 OK

Successfully retrieved validator responses for a data request.

Schema

Name	Type	Required	Restrictions	Description
ok	boolean	true	none	none
validatorResponses	dict<ValidatorId, ValidatorResponse>	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	string<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	Participant	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	TrusteeId or ValidatorId	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