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
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
​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
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
​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
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
​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
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
​Ciphertext​
true
none
ciphertext
​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
​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
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
array<ValidatorId>
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}/
Operator
Decryptor
Last modified 5mo ago