Implementation

Technical steps to implement the API

This is the ExeQuantum API for post quantum encryption. It uses ML-KEM for key encapsulation, as it was the NIST's choice for its post quantum security standardization competition.

It also utilizes its digital signature counterpart, ML-DSA, to digitally sign the key and verify its origin.

Unlike other algorithms like RSA, ML-KEM doesn't perform the encryption per se. Rather, it uses key encapsulation to generate a shared secret for symmetric encryption-decryption.

Example use cases for ML-KEM:

• End to End Encryption

• TLS

• Symmetric Encryption

Example use cases for ML-DSA:

• Message verification

• Blockchain/Cryptocurrency proof of ownership

Below are the steps for ML-KEM and ML-DSA.

Before starting: Get your API token

PQCaaS uses an authentication token to allow calls into our API. When you sign up, you'll get a root token that does not expire (unless you reset it). It will appear in your dashboard, hidden until you choose to expose it, like so:

API dashboard

You can also copy it without showing it, if you need extra privacy.

It is highly recommended that you only use this token from secure environments, and only use temporary (ideally single use) tokens when making calls from more exposed environments like frontend. Steps to generate a temporary tokens will be described later in this documentation.

Below that, you'll see the dashboard that shows your API usage for the month. Keep an eye on it to track your usage.

Usage metric and cost

That's basically it for the dashboard. Now we can begin the integration steps. If you want to learn a bit more the high level overview of how ML-KEM and ML-DSA work, please refer to the Getting Started page.

RECOMMENDED Step 0 (ML-KEM and ML-DSA): Generate a temporary token

In order to avoid overusing your sensitive authorization token, it's recommended to generate a temporary token that can be used for API calls.

You'll have to use the auth token for this call, so make sure to do it in a secure environment (i.e. backend)

This would be especially recommended when the API has to be called at areas where it has to be exposed to clients (i.e. frontend).

You can still use the auth token from your dashboard, at your own discretion.

You can determine how long the token should persist for (in seconds) through the expiry_time parameter. The default is 300 seconds or 5 minutes.

It's recommended to keep it relatively short (i.e. the average length of a session on your app) and handle switching as needed.

The token also has a limited number of times that it can get called. By default it's 1 attempt per token, and it's highly recommended

to keep it at 1, just to encapsulate the key in the frontend, but if you have to, you can set the number of retries allowed with the

parameter expire_after_attempts.

Note: examples are in Python, but the API can fit in every language.

Step 0:

import requests

response = requests.get(
    'https://api.exequantum.com/api/token/new',
    headers={'Authorization': 'bearer ' + AUTH_TOKEN}
)
temp_token = response.json()['new_token']
headers = {'Authorization': 'bearer ' + temp_token}

The procedure to create a shared secret for symmetric encryption-decryption purposes will be as follows:

ML-KEM - Step A (by person A):

headers = {'Authorization': 'Bearer ' + AUTH_TOKEN}

response = requests.get(
    'https://api.exequantum.com/api/kem/generate_keys',
    headers=headers
)
keys = response.json()

public_key = keys['pk']
secret_key = keys['sk']
verification_key = keys['verification_key']
verification_signature = keys['verification_signature']

This generates a key pair that gets sent over for encapsulation and decapsulation. The secret key gets encrypted before being sent over, and can only be used by us.

The verification key and signature are necessary for the ML-DSA signature on the public key to prevent tampering. The private signature key does not need to be shared for verification.

Person A will sent the public key, verification key and verification signature to person B, while keeping the secret key secured with themselves.

ML-KEM - Step B (by person B):

body = {
    'pk': public_key,
    'verif_key': verification_key,
    'signature': verification_signature
}
response = requests.post(
    'https://api.exequantum.com/api/kem/encapsulate_key',
    headers=headers,
    json=body
)
enc = response.json()
cipher = enc['cipher']
shared_secret = enc['shared_key']

This API endpoint generates a shared secret that will be used for symmetric encryption. It should not be shared.

The cipher and the encrypted secret key can be sent back for the key decapsulation.

ML-KEM - Step C (by person A):

body = {
    'cipher': cipher,
    'sk': secret_key
}
response = requests.post(
    'https://api.exequantum.com/api/kem/decapsulate_key',
    headers=headers,
    json=body
)
dec = response.json()
shared_secret = dec['shared_key']

This API point generates the same shared secret. The cipher and secret keys are used for it.

Now that both sides of the communications have a secured shared secret, the secure communication can commence.

It is recommended to use AES256 for the encryption and decryption, as they're considered Quantum secure.

AES encryption and decryption are offered as API endpoints for free (Key generation and encapsulations are $1 per 4,000 requests), but you can feel free to use your own encryption.

If you decide to use our API for AES, it will go as follows:

ML-KEM - Step D (By encryptor):

body = {
    'unencrypted': 'hello world',
    'key': shared_secret
}
response = requests.post(
    'https://api.exequantum.com/api/aes/encrypt_text',
    headers=headers,
    json=body
)
encrypted_message = response.json()

This API call encrypted the message. Now to decrypt, the decryptor can just use the shared secret created by ML-KEM to decrypt the message.

ML-KEM - Step E (By decryptor):

body = {
    'ciphertext': encrypted_message,
    'key': shared_secret
}
response = requests.post(
    'https://api.exequantum.com/api/aes/decrypt_text',
    headers=headers,
    json=body
)
decrypted_message = response.json()

print("Decrypted message:", decrypted_message)

And that's it! You got your Quantum secure communication channel. If you want to learn more, feel free to book a demo.

Below are the steps to use ML-DSA

ML-DSA - Step A (By person A):

body = {
    'data': data
}
response = requests.post(
    'https://api.exequantum.com/api/signature/sign',
    headers=headers,
    json=body
)

data = response.json()

pk = data['pk']
sk = data['sk']
signature = data['signature']

From the endpoint, you get the generated signature and the public key that is used to verify the signature, as well as the secret key used to generate it.

The data, public key and signature should be sent over to person B, while person A needs to keep the secret key secure.

ML-DSA - Step B (By person B):

body = {
    'data': data,
    'pk': pk,
    'signature': signature
}
response = requests.post(
    'https://api.exequantum.com/api/signature/verify',
    headers=headers,
    json=body
)

data = response.json()

verified = data['verified']

The verified data will indicate whether the signature is valid. It returns false is the signature or data was tampered with and true if it's all good.

To see the terms and conditions of our API click here.

Generate Token

Parameters: expiry_time (optional), expire_after_attempts (optional)

Headers: Authorization token

Response: { 'new_token': string }

Documentation: This API endpoint generates a temporary token, that lasts a set amount of time and can be used for a set amount of attempts.

GET/api/token/new

Query parameters

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/token/new', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Generate Keys

Parameters: None

Headers: Authorization token

Response: { 'pk': string, 'verification_key': string }

Documentation: This API endpoint generates a key pair, a public key (pk) and a secret key (sk). It also generates a verification key and a signature for digital verification purposes. The public key can be sent over to the message sender for encapsulation. The secret key gets stored privately for later retrieval.

GET/api/kem/generate_keys

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/kem/generate_keys', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Encapsulate Key

Body: pk, signature, verif_key

Headers: Authorization token

Response: { 'cipher': string, 'shared_key': string }

Documentation: This API endpoint uses the public key to encapsulate the key, which generates a random cipher and a shared secret. The cipher can be sent back to the message sender to use for decapsulation.

POST/api/kem/encapsulate_key

Body

application/json

pk*Pk

signature*Signature

verif_key*Verif Key

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/kem/encapsulate_key', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "pk": "text",
      "signature": "text",
      "verif_key": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Decapsulate Key

Parameters: cipher, pk

Headers: Authorization token

Response: { 'shared_key': string }

Documentation: This API endpoint uses the the random cipher to generate a shared secret. If done correctly, this shared secret will now be only in the possession of the message sender and receiver and can be used as a symmetrical key to encrypt and decrypt any further data communication.

POST/api/kem/decapsulate_key

Body

application/json

cipher*Cipher

sk*Sk

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/kem/decapsulate_key', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "cipher": "text",
      "sk": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Sign

Body: data

Headers: Authorization token

Response: { 'signature': string, 'pk': string }

Documentation: This API endpoint generates a digital signature on the data.

POST/api/signature/sign

Body

application/json

data*Data

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/signature/sign', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Verify

body: data, pk, signature

Headers: Authorization token

Response: { 'verified': boolean }

Documentation: This API endpoint uses the signature and a public key to verify the origin of the data

POST/api/signature/verify

Body

application/json

data*Data

pk*Pk

signature*Signature

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/signature/verify', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": "text",
      "pk": "text",
      "signature": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Encrypt Text

Body: unencrypted

Headers: Authorization token

Response: Encrypted message text

Documentation: This API endpoint uses the shared key to perform an AES encryption on a string (can be base64 or hex).

POST/api/aes/encrypt_text

Body

application/json

unencrypted*Unencrypted

key*Key

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/aes/encrypt_text', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "unencrypted": "text",
      "key": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Decrypt Text

Body: key, ciphertext

Headers: Authorization token

Response: Decrypted message text

Documentation: This API endpoint uses the shared key to perform an AES decryption on a fstringile.

POST/api/aes/decrypt_text

Body

application/json

ciphertext*Ciphertext

key*Key

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/aes/decrypt_text', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "ciphertext": "text",
      "key": "text"
    }),
});
const data = await response.json();

Response

422

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}