Encryptor

Create a channel for a secret and upload an encryption

POST /encryptions

Description

Secrets are secured within a channel of a PAD instance. To create an encryption Channel, you must upload an Encryption object to the server. At any time, the decryptor can retrieve the Encryption object using the hash of the token value, which acts as an identifier of the channel. The decryptor may choose to retrieve the Encryption object immediately in order to independently store the encrypted values, or may only do so when a decryption is requested. In any case, no decryption can occur unless the decryptor has posted a data request and sufficient trustees and validators have responded. Read the code samples section for details and information about how to construct Encryption objects.

To facilitate updating the Encryption object securely in some use cases (Find-me, for example), you can send a channel key along with this request. This ensures only you who has the private key counterpart of the channel key can change the Encryption object in this channel.

Parameters

Name	In	Type	Required	Description
encryption	body	Encryption	true	none
channelKey	body	string	true	A PEM-encoded (public) verification key for the channel

Example

{
  "encryption": {
    "description": "string",
    "tokenHash": "d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4",
    "ciphertext": {
      "encryptedMessage": {
        "ciphertext": "base64_encoded_data",
        "iv": "base64_encoded_data"
      },
      "encryptedEphemeralKey": "base64_encoded_data"
    },
    "trusteeShares": {
      "trustee1": {
        "encrypted": "base64_encoded_data",
        "hashed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      }
    },
    "validatorShares": {
      "validator1": {
        "encrypted": {
          "encryptedMessage": {
            "ciphertext": "base64_encoded_data",
            "iv": "base64_encoded_data"
          },
          "encryptedEphemeralKey": "base64_encoded_data"
        }
      }
    },
  },
  "channelKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5fYv3lbLtDjR5IxAurWF6TMfhNZB\nPUn2DLapmjLWvZXYjqSrflJx4TemksjRyMDi+CwWP0PkunBB6wUdCDmdWA==\n-----END PUBLIC KEY-----"
}

Responses

Status	Meaning	Description	Schema
200	OK	Succeeded	ApiResponse
401	Unauthorized	API key is missing or invalid	ApiResponse
409	Conflict	Conflict	ApiResponse

200 OK

The encryption has been successfully uploaded onto the server.

Example

{
  "ok": true,
  "message": "Successfully uploaded encryption",
}

401 Unauthorized

API key is missing or incorrect.

Example

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

409 Conflict

A channel with the same token already exists. The client should use another token or update the encryption on the channel.

Example

{
  "ok": false,
  "message": "The encryption with token hash ${tokenHash} already exists. Update it with PUT request or renew the token.",
}

Get encryption status

GET /encryptions/{token-hash}/status

Description

This retrieves the status of an encryption, namely whether or not the data has been requested by the decryptor. If a request has been made, then this status also gives which trustees and validators have responded to the data request. This information is retrieved and provided by the PAD server. To eliminate the need to trust the PAD service, this data should be checked for consistency with trustee attestations of the ledger state.

Parameters

Name	In	Type	Required	Description
token-hash	path	Sha256	true	Hash value of the token in hexadecimal

Example

GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/status

Responses

Status	Meaning	Description	Schema
200	OK	Succeeded	Inline
401	Unauthorized	API key is missing or invalid; Or the client lacks permission	ApiResponse

200 OK

Successfully retrieved the status of an Encryption.

Schema

Name	Type	Required	Restrictions	Description
ok	boolean	true	none	none
encryptionStatus	object	true	none	none
» tokenHash	Sha256	true	none	none
» requested	boolean	true	none	none
» token	Token	false	none	none
» requestTime	DateTime	false	none	none
» respondedTrustees	array<TrusteeId>	false	none	none
» respondedValidators	array<ValidatorId>	false	none	none

Example

{
  "ok": true,
  "encryptionStatus": {
    "tokenHash": "d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4",
    "requested": true,
    "token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
    "requestTime": "2021-05-05T13:53:19.275Z",
    "respondedTrustees": [
      "trustee1"
    ],
    "respondedValidators": [
      "validator1"
    ]
  }
}

401 Unauthorized

API key is missing or incorrect.

Example

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

Update encryption

PUT /encryptions/{token-hash}

Description

In some use cases (e.g. Find-me), secrets may be generated as a stream of data and the decryptor can make a request for only the most recent secret. This endpoint allows the encryptor to update the Encryption after establishing an encryption channel.

To ensure only you can use this endpoint, you must sign the Encryption object with the channel private key.

Parameters

Name	In	Type	Required	Description
token-hash	path	Sha256	true	Hash value of the token
encryptionPayload	body	string<Encryption>	true	The new, stringified encryption object
signature	body	Base64	true	The signature with the channel private key against encryptionPayload

Example

PUT /encryptions/d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4

{
  "encryptionPayload": "{\"description\":\"string\",\"tokenHash\":\"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4\",\"ciphertext\":{\"encryptedMessage\":{\"ciphertext\":\"base64_encoded_data\",\"iv\":\"base64_encoded_data\"},\"encryptedEphemeralKey\":\"base64_encoded_data\"},\"trusteeShares\":{\"trustee1\":{\"encrypted\":\"base64_encoded_data\",\"hashed\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\"}},\"validatorShares\":{\"validator1\":{\"encrypted\":{\"encryptedMessage\":{\"ciphertext\":\"base64_encoded_data\",\"iv\":\"base64_encoded_data\"},\"encryptedEphemeralKey\":\"base64_encoded_data\"}}}}",
  "signature": "MEQCIGuYVL9wh/4TawM1bFSB5MmF4FkqJPcppj66xc2+MRdHAiBNEF8w77J6SLq3UtxgIRw5Hl8C2JKVUwaKHLflkoaI0w=="
}

Responses

Status	Meaning	Description	Schema
200	OK	Succeeded	ApiResponse
400	Bad Request	Tokens in path and body are inconsistent	ApiResponse
401	Unauthorized	API key is missing or invalid; Or the client lacks permission	ApiResponse

200 OK

The Encryption is successfully updated.

Example

{
  "ok": true,
  "message": "Successfully updated encryption"
}

400 Bad Request

The request failed because tokens in path and body are inconsistent.

Example

{
  "ok": false,
  "message": "Token hashes in path and body must be consistent",
}

401 Unauthorized

Api key is missing or incorrect.

Example

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

Schemas

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}

Encryption

An Encryption is identified by tokenHash and the instance in which it lives. It contains the ciphertext encrypted by both the decryptor's key and a fresh symmetric key k. It also contains the encrypted shares of k for the trustees and validators. For more details, read the code samples page.

Example

{
  "description": "string",
  "tokenHash": "hex_encoded_string",
  "ciphertext": {
    "encryptedMessage": {
      "ciphertext": "base64_encoded_string",
      "iv": "base64_encoded_string",
    },
    "encryptedEphemeralKey": "base64_encoded_string",
  },
  "trusteeShares": {
    "trustee1": {
      "encrypted": "base64_encoded_string",
      "hashed": "hex_encoded_string",
    },
  },
  "validatorShares": {
    "validator1": {
      "encrypted": {
        "encryptedMessage": {
          "ciphertext": "base64_encoded_string",
          "iv": "base64_encoded_string",
        },
        "encryptedEphemeralKey": "base64_encoded_string",
      },
    },
  },
}

Schema

Name	Type	Required	Description
description	string	true	none
tokenHash	Sha256	true	none
trusteeShares	dict<TrusteeId, object>	true	none
» [trusteeId]	object	true	none
»» encrypted	string	true	none
»» hashed	Sha256	true	none
validatorShares	dict<ValidatorId, object>	true	none
» [validatorId]	object	true	none
»» encrypted	Ciphertext	true	none
ciphertext	Ciphertext	true	none

Sha256

A Sha256 hash value as a hexidecimal string.

Example

"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"

Schema

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

DateTime

A timestamp in ISO 8601 format.

Example

"2021-05-05T13:53:19.275Z"

Schema

Type	Restrictions
string	-

Trustee

An object listing details of a trustee, including its ID, human-readable description/name, its role (Trustee) and its public keys.

Example

{
  "id": "trustee1",
  "fullName": "Trustee-1",
  "role": "Trustee",
  "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----\n",
  "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
}

Schema

Name	Type	Required	Restrictions	Description
id	TrusteeId	true	/[0-9a-zA-Z-_]{3,30}/	none
fullName	string	true	/Trustee-[0-9a-zA-Z_]+/	none
role	enum	true	none	none
encryptionKey	string	true	none	PEM-encoded (public) encryption key of the trustee. Used by encryptors at encryption time
verificationKey	string	true	none	PEM-encoded (public) verification key of trustee

Enumerated Values

Property	Value
role	Trustee

Validator

An object listing details of a validator, including its ID, human-readable description/name, its role (Validator) and its public keys.

Example

{
  "id": "validator1",
  "fullName": "Validator1",
  "role": "Validator",
  "encryptionKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvAnBzaNLM8/iIxP0Rz88\nQk7mj+TW1U1C2BQAaOAQfRTRrEsNDVPpAZB8LTfs8wZEhok5VzSMA4dPTkQE8Su8\np/eQJthOTCmBq2t8dgx0+uX3IhdwXgmWCh0OQ8NJ94rXA+/rWqjeNXZ4ShFlNDeu\nkv9OGLh4bvSTUHWzDi6M4qxlq8fJ/O+lTvJzf6cb6n7pKpT7/ppdGik/Hi8EcQiY\nSL9lbAkKJpgrfqWNDo7HX/2GffZdd316123stOqrBTZS81Ow/Z/rqiPvzBV1HxEv\nabfIFd1LefWgBfECoXOpvYaBuL4N6fchX9gAis7J66WFDQVZsnJ/J3Bzl0ECRgVp\n8QIDAQAB\n-----END PUBLIC KEY-----\n",
  "verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
}

Schema

Name	Type	Required	Restrictions	Description
id	ValidatorId	true	-	none
fullName	string	true	/Validator-[0-9a-zA-Z_]+/	none
`role	enum`	true	none	none
encryptionKey	string	true	none	PEM-encoded (public) encryption key of the validator. Used by encryptors at encryption time
verificationKey	string	true	none	PEM-encoded (public) verification key of validator

Enumerated Values

Property	Value
role	Validator

Base64

A base64-encoded binary data.

Example

"aGVsbG8gd29ybGQ="

Schema

Type	Restrictions
string	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

PadInstanceMetadata

Information about a PAD instance. That includes the instance name, its list of trustees, the trustee threshold, the list of validators and the validator threshold.

Example

{
  "padName": "my-pad-1.0",
  "trusteeIds": [
    "trustee1",
    "trustee2",
  ],
  "t": 1,
  "validatorIds": [
    "validator1",
    "validator2",
  ],
  "tPrime": 1,
}

Schema

Name	Type	Required	Restrictions	Description
padName	PadName	true	none	none
trusteeIds	array<TrusteeId>	true	none	none
t	integer	true	none	none
validatorIds	array<ValidatorId>	true	none	none
tPrime	integer	true	none	none

ApiResponse

Example

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

Schema

Name	Type	Required	Description
ok	boolean	true	The request is successful or not
message	string	true	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}/

PadName

ID of a PAD instance. Its length must be inclusively between 4 and 30. It should contains only lowercase letters, digits, periods (.) or dashes (-). It must start with a lowercase letter.

It is seldom used as a request parameter because the API key in the request already identifies a PAD instance.

Example

"my-pad-1.0"

Schema

Type	Restrictions
string	/[a-z][a-z0-9.-]{3,29}/