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

NameInTypeRequiredDescription

-

body

DataRequest

true

none

Example

{
  "token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}

Responses

StatusMeaningDescriptionSchema

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

NameInTypeRequiredDescription

token-hash

path

Sha256

true

Hash value of the token

Example

GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/ciphertext

Responses

StatusMeaningDescriptionSchema

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

NameTypeRequiredRestrictionsDescription

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

NameInTypeRequiredDescription

token

body

Token

true

none

Example

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

Responses

StatusMeaningDescriptionSchema

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

NameTypeRequiredRestrictionsDescription

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

NameInTypeRequiredDescription

token

body

Token

true

none

Example

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

Responses

StatusMeaningDescriptionSchema

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

NameTypeRequiredRestrictionsDescription

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

NameTypeRequiredRestrictionsDescription

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

NameTypeRequiredRestrictionsDescription

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

TypeRestrictions

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

TypeRestrictions

string

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

Sha256

A Sha256 hash value as a hexidecimal string.

Example

"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"

Schema

TypeRestrictions

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

TypeRestrictions

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

TypeRestrictions

string

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

ApiResponse

Example

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

Schema

NameTypeRequiredDescription

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

NameTypeRequiredRestrictionsDescription

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

PropertyValue

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

NameTypeRequiredDescription

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

NameTypeRequiredDescription

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

NameTypeRequiredDescription

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

PropertyValue

role

Trustee

role

Validator

role

Server

PreviousEncryptorNextTrustee

Last updated