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
true
none
channelKey
body
string
true
A PEM-encoded (public) verification key for the channel
Example
1
{
2
"encryption": {
3
"description": "string",
4
"tokenHash": "d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4",
5
"ciphertext": {
6
"encryptedMessage": {
7
"ciphertext": "base64_encoded_data",
8
"iv": "base64_encoded_data"
9
},
10
"encryptedEphemeralKey": "base64_encoded_data"
11
},
12
"trusteeShares": {
13
"trustee1": {
14
"encrypted": "base64_encoded_data",
15
"hashed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
16
}
17
},
18
"validatorShares": {
19
"validator1": {
20
"encrypted": {
21
"encryptedMessage": {
22
"ciphertext": "base64_encoded_data",
23
"iv": "base64_encoded_data"
24
},
25
"encryptedEphemeralKey": "base64_encoded_data"
26
}
27
}
28
},
29
},
30
"channelKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5fYv3lbLtDjR5IxAurWF6TMfhNZB\nPUn2DLapmjLWvZXYjqSrflJx4TemksjRyMDi+CwWP0PkunBB6wUdCDmdWA==\n-----END PUBLIC KEY-----"
31
}
Copied!

Responses

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

200 OK

The encryption has been successfully uploaded onto the server.
Example
1
{
2
"ok": true,
3
"message": "Successfully uploaded encryption",
4
}
Copied!

401 Unauthorized

API key is missing or incorrect.
Example
1
{
2
"ok": false,
3
"message": "Unauthorized",
4
}
Copied!

409 Conflict

A channel with the same token already exists. The client should use another token or update the encryption on the channel.
Example
1
{
2
"ok": false,
3
"message": "The encryption with token hash ${tokenHash} already exists. Update it with PUT request or renew the token.",
4
}
Copied!

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
API key is missing or invalid; Or the client lacks permission

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
false
none
none
Example
1
{
2
"ok": true,
3
"encryptionStatus": {
4
"tokenHash": "d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4",
5
"requested": true,
6
"token": "0fe5ff17c6ee6efa8ca385587b1e1ac2",
7
"requestTime": "2021-05-05T13:53:19.275Z",
8
"respondedTrustees": [
9
"trustee1"
10
],
11
"respondedValidators": [
12
"validator1"
13
]
14
}
15
}
Copied!

401 Unauthorized

API key is missing or incorrect.
Example
1
{
2
"ok": false,
3
"message": "Unauthorized",
4
}
Copied!

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
1
{
2
"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\"}}}}",
3
"signature": "MEQCIGuYVL9wh/4TawM1bFSB5MmF4FkqJPcppj66xc2+MRdHAiBNEF8w77J6SLq3UtxgIRw5Hl8C2JKVUwaKHLflkoaI0w=="
4
}
Copied!

Responses

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

200 OK

The Encryption is successfully updated.
Example
1
{
2
"ok": true,
3
"message": "Successfully updated encryption"
4
}
Copied!

400 Bad Request

The request failed because tokens in path and body are inconsistent.
Example
1
{
2
"ok": false,
3
"message": "Token hashes in path and body must be consistent",
4
}
Copied!

401 Unauthorized

Api key is missing or incorrect.
Example
1
{
2
"ok": false,
3
"message": "Unauthorized",
4
}
Copied!

Schemas

TrusteeId

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

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

1
my_validator-2
Copied!

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
1
{
2
"description": "string",
3
"tokenHash": "hex_encoded_string",
4
"ciphertext": {
5
"encryptedMessage": {
6
"ciphertext": "base64_encoded_string",
7
"iv": "base64_encoded_string",
8
},
9
"encryptedEphemeralKey": "base64_encoded_string",
10
},
11
"trusteeShares": {
12
"trustee1": {
13
"encrypted": "base64_encoded_string",
14
"hashed": "hex_encoded_string",
15
},
16
},
17
"validatorShares": {
18
"validator1": {
19
"encrypted": {
20
"encryptedMessage": {
21
"ciphertext": "base64_encoded_string",
22
"iv": "base64_encoded_string",
23
},
24
"encryptedEphemeralKey": "base64_encoded_string",
25
},
26
},
27
},
28
}
Copied!

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

Sha256

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

Schema

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

DateTime

A timestamp in ISO 8601 format.
Example
1
"2021-05-05T13:53:19.275Z"
Copied!

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
1
{
2
"id": "trustee1",
3
"fullName": "Trustee-1",
4
"role": "Trustee",
5
"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",
6
"verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
7
}
Copied!

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
1
{
2
"id": "validator1",
3
"fullName": "Validator1",
4
"role": "Validator",
5
"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",
6
"verificationKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELZyXL9AOgZrIsWrDkY0ohQuvMsVa\n+3eJSfsV+a1HW0M34lZInCVPgule/a9HqnqpDtXEBclgeeKS1YT7jVjpTg==\n-----END PUBLIC KEY-----",
7
}
Copied!

Schema

Name
Type
Required
Restrictions
Description
id
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
1
"aGVsbG8gd29ybGQ="
Copied!

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
1
{
2
"encryptedMessage": {
3
"ciphertext": "base64_encoded_data=",
4
"iv": "base64_encoded_data=",
5
},
6
"encryptedEphemeralKey": "base64_encoded_data=",
7
}
Copied!

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
1
{
2
"padName": "my-pad-1.0",
3
"trusteeIds": [
4
"trustee1",
5
"trustee2",
6
],
7
"t": 1,
8
"validatorIds": [
9
"validator1",
10
"validator2",
11
],
12
"tPrime": 1,
13
}
Copied!

Schema

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

ApiResponse

Example
1
{
2
"ok": true,
3
"message": "string",
4
}
Copied!

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
1
"0fe5ff17c6ee6efa8ca385587b1e1ac2"
Copied!

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
1
"my-pad-1.0"
Copied!

Schema

Type
Restrictions
string
/[a-z][a-z0-9.-]{3,29}/
Last modified 5mo ago