# Decryptor

## Post data request <a href="#op-post-data-request" id="op-post-data-request"></a>

`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](#schema-data-request) | true     | none        |

**Example**

```json
{
  "token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}
```

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | [ApiResponse](#schema-api-response) |
| 400    | Bad Request                                                     | Invalid token                 | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |
| 409    | [Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)   | Conflict                      | [ApiResponse](#schema-api-response) |

#### 200 OK

The data request is successfully posted on the ledger.

**Example**

```json
{
  "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**

```json
{
  "ok": false,
  "message": "Wrong type at body.token",
}
```

**Example 2**

```json
{
  "ok": false,
  "message": "wrong length at body.token. Expected: 32; given: 64",
}
```

#### 401 Unauthorized

API key is missing or incorrect.

**Example**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

#### 409 Conflict

The data request has already been posted.

**Example**

```json
{
  "ok": false,
  "message": "Data request has been posted before",
}
```

## Get ciphertext <a href="#op-get-ciphertext" id="op-get-ciphertext"></a>

`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](https://docs.padprotocol.org/code_samples_enc_dec) to see how decryptions are done.

### Parameters

| Name       | In   | Type                     | Required | Description             |
| ---------- | ---- | ------------------------ | -------- | ----------------------- |
| token-hash | path | [Sha256](#schema-sha256) | true     | Hash value of the token |

**Example**

`GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/ciphertext`

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |
| 404    | Not found                                                       | Encryption not found          | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved the ciphertext from the `encryption`.

**Schema**

| Name       | Type                             | Required | Restrictions | Description |
| ---------- | -------------------------------- | -------- | ------------ | ----------- |
| ok         | boolean                          | true     | none         | none        |
| ciphertext | [Ciphertext](#schema-ciphertext) | true     | none         | none        |

**Example**

```json
{
  "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**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

#### 404 Not found

The encryption does not exist.

**Example**

```json
{
  "ok": false,
  "message": "Encryption with token hash d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4 not found",
}
```

## Get trustee responses <a href="#op-get-trustee-responses" id="op-get-trustee-responses"></a>

`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](https://docs.padprotocol.org/code_samples_enc_dec) 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](#schema-token) | true     | none        |

**Example**

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

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 400    | Bad Request                                                     | Token is invalid in format    | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |
| 404    | Not found                                                       | Encryption not found          | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved trustee responses for a data request.

**Schema**

| Name             | Type                                                                                            | Required | Restrictions | Description |
| ---------------- | ----------------------------------------------------------------------------------------------- | -------- | ------------ | ----------- |
| ok               | boolean                                                                                         | true     | none         | none        |
| trusteeResponses | dict<[TrusteeId](#schema-trustee-id), [SignedTrusteeResponse](#schema-signed-trustee-response)> | true     | none         | none        |

**Example**

```json
{
  "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**

```json
{
  "ok": false,
  "message": "wrong length at path.token. Expected: 32; given 31",
}
```

#### 401 Unauthorized

API key is missing or incorrect.

**Example**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

#### 404 Not found

The data request does not exist.

**Example**

```json
{
  "ok": false,
  "message": "Data request not found",
}
```

## Get validator responses <a href="#op-get-validator-responses" id="op-get-validator-responses"></a>

`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](https://docs.padprotocol.org/code_samples_enc_dec)

> 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](#schema-token) | true     | none        |

**Example**

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

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 400    | Bad Request                                                     | Token is invalid in format    | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |
| 404    | Not found                                                       | Encryption not found          | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved validator responses for a data request.

**Schema**

| Name               | Type                                                                                       | Required | Restrictions | Description |
| ------------------ | ------------------------------------------------------------------------------------------ | -------- | ------------ | ----------- |
| ok                 | boolean                                                                                    | true     | none         | none        |
| validatorResponses | dict<[ValidatorId](#schema-validator-id), [ValidatorResponse](#schema-validator-response)> | true     | none         | none        |

**Example**

```json
{
  "ok": true,
  "validatorResponses": {
    "validator1": {
      "validatorResponse": ,
      "signature": {
        "signerMetdata": {
          "id": "validator1",
          "fullName": "Validator-1",
          "role": "Validator",
        },
      },
    },
  },
}
```

#### 400 Bad Request

Request is malformed.

**Example**

```json
{
  "ok": false,
  "message": "wrong length at path.token. Expected: 32; given 31",
}
```

#### 401 Unauthorized

API key is missing or incorrect.

**Example**

```json
{
  "ok": false,
  "message": "Unauthorized",
}
```

#### 404 Not found

The data request does not exist.

**Example**

```json
{
  "ok": false,
  "message": "Data request not found",
}
```

## Schemas

### DataRequest <a href="#schema-data-request" id="schema-data-request"></a>

A data request, containing a token whose hash value was provided by the encryptor at encryption time.

**Example**

```json
{
  "token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
}
```

#### Schema

| Name  | Type                   | Required | Restrictions | Description |
| ----- | ---------------------- | -------- | ------------ | ----------- |
| token | [Token](#schema-token) | true     | none         | none        |

### Ciphertext <a href="#schema-ciphertext" id="schema-ciphertext"></a>

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](https://docs.padprotocol.org/code_samples_enc_dec).

**Example**

```json
{
  "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](#schema-base64) | true     | none         | none                                                        |
| » iv                  | [Base64](#schema-base64) | true     | none         | none                                                        |
| encryptedEphemeralKey | [Base64](#schema-base64) | true     | none         | The ephemeral key encrypted by an asymmetric encryption key |

### Base64 <a href="#schema-base64" id="schema-base64"></a>

A base64-encoded binary data.

**Example**

```json
"aGVsbG8gd29ybGQ="
```

#### Schema

| Type   | Restrictions |
| ------ | ------------ |
| string | none         |

### Token <a href="#schema-token" id="schema-token"></a>

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 href="#schema-sha256" id="schema-sha256"></a>

A Sha256 hash value as a hexidecimal string.

**Example**

```json
"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"
```

#### Schema

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

### TrusteeId <a href="#schema-trustee-id" id="schema-trustee-id"></a>

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 <a href="#schema-validator-id" id="schema-validator-id"></a>

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 <a href="#schema-api-response" id="schema-api-response"></a>

**Example**

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

#### Schema

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

### TrusteeResponse <a href="#schema-trustee-response" id="schema-trustee-response"></a>

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**

```json
{
    "padName": "my-pad-1.0",
    "token": "e3b0c44298fc1c149afbf4c8996fb924",
    "trusteeShare": "0110",
    "type": "trustee_response",
    "trusteeId": "trustee1",
}
```

#### Schema

| Name         | Type                            | Required | Restrictions | Description                                   |
| ------------ | ------------------------------- | -------- | ------------ | --------------------------------------------- |
| padName      | [PadName](#schema-pad-name)     | true     | none         | The instance where the data request is posted |
| token        | [Token](#schema-token)          | true     | none         | The ID of the data request                    |
| trusteeShare | [Base64](#schema-base64)        | true     | none         | The decrypted trustee share                   |
| type         | enum                            | true     | none         | Type of response                              |
| trusteeId    | [TrusteeId](#schema-trustee-id) | true     | none         | ID of the responding trustee                  |

#### Enumerated Values

| Property | Value                |
| -------- | -------------------- |
| type     | `"trustee_response"` |

### SignedTrusteeResponse <a href="#schema-signed-trustee-response" id="schema-signed-trustee-response"></a>

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**

```json
{
  "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](#schema-trustee-response)> | true     | none        |
| signature       | [Signature](#schema-signature)                      | true     | none        |

### Signature <a href="#schema-signature-href-schema-signature-href-schema-signature" id="schema-signature-href-schema-signature-href-schema-signature"></a>

A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.

**Schema**

```json
{
  "signerMetadata": {
    "id": "string",
    "fullName": "string",
    "role": "Trustee",
  },
  "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ==",
}
```

#### Schema

| Name           | Type                               | Required | Description |
| -------------- | ---------------------------------- | -------- | ----------- |
| signerMetadata | [Participant](#schema-participant) | false    | none        |
| payload        | [Base64](#schema-base64)           | false    | none        |

### Participant <a href="#schema-participant-href-schema-participant-href-schema-participant" id="schema-participant-href-schema-participant-href-schema-participant"></a>

Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.

**Example**

```json
{
  "id": "my_trustee-1",
  "fullName": "Trustee-1",
  "role": "Trustee"
}
```

#### Schema

| Name     | Type                                                                   | Required | Description                                              |
| -------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| id       | [TrusteeId](#schema-trustee-id) or [ValidatorId](#schema-validator-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    |