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
Example
Responses
200 OK
The data request is successfully posted on the ledger.
Example
400 Bad Request
Input is malformed. Check that:
token
is a stringtoken
is a 128-bit hex string
Example 1
Example 2
401 Unauthorized
API key is missing or incorrect.
Example
409 Conflict
The data request has already been posted.
Example
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
Example
GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/ciphertext
Responses
200 OK
Successfully retrieved the ciphertext from the encryption
.
Schema
ok
boolean
true
none
none
Example
401 Unauthorized
API key is missing or incorrect.
Example
404 Not found
The encryption does not exist.
Example
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
Example
GET /data-requests/{token}/trustee-responses
Responses
200 OK
Successfully retrieved trustee responses for a data request.
Schema
ok
boolean
true
none
none
Example
400 Bad Request
Request is malformed.
Example
401 Unauthorized
API key is missing or incorrect.
Example
404 Not found
The data request does not exist.
Example
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
Example
GET /data-requests/{token}/validator-responses
Responses
200 OK
Successfully retrieved validator responses for a data request.
Schema
ok
boolean
true
none
none
Example
400 Bad Request
Request is malformed.
Example
401 Unauthorized
API key is missing or incorrect.
Example
404 Not found
The data request does not exist.
Example
Schemas
DataRequest
A data request, containing a token whose hash value was provided by the encryptor at encryption time.
Example
Schema
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
Schema
Base64
A base64-encoded binary data.
Example
Schema
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
Schema
string
/[0-9a-fA-Z]{32}/
Sha256
A Sha256 hash value as a hexidecimal string.
Example
Schema
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
Schema
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
Schema
string
[a-zA-Z0-9-_]{3,30}
ApiResponse
Example
Schema
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
Schema
Enumerated Values
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
Schema
Signature
A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.
Schema
Schema
Participant
Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.
Example
Schema
fullName
string
true
/Trustee-[0-9a-zA-Z_]+/
or /Validator-[0-9a-zA-Z_]+/
role
enum
true
none
Enumerated Values
role
Trustee
role
Validator
role
Server
Last updated