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

NameInTypeRequiredDescription

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

StatusMeaningDescriptionSchema

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

NameInTypeRequiredDescription

token-hash

path

Sha256

true

Hash value of the token in hexadecimal

Example

GET /encryptions/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855/status

Responses

StatusMeaningDescriptionSchema

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

NameTypeRequiredRestrictionsDescription

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

NameInTypeRequiredDescription

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

StatusMeaningDescriptionSchema

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

TypeRestrictions

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

TypeRestrictions

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

NameTypeRequiredDescription

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

TypeRestrictions

string

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

DateTime

A timestamp in ISO 8601 format.

Example

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

Schema

TypeRestrictions

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

NameTypeRequiredRestrictionsDescription

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

PropertyValue

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

NameTypeRequiredRestrictionsDescription

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

PropertyValue

role

Validator

Base64

A base64-encoded binary data.

Example

"aGVsbG8gd29ybGQ="

Schema

TypeRestrictions

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

NameTypeRequiredRestrictionsDescription

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

NameTypeRequiredRestrictionsDescription

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

NameTypeRequiredDescription

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

TypeRestrictions

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

TypeRestrictions

string

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

PreviousOperatorNextDecryptor

Last updated