Encrypt / Decrypt

2026-02-20 2026-02-20 v0.1.x-beta

1. What is it?

The Encrypt / Decrypt section exposes the core Encryption-as-a-Service (EaaS) operations: encrypt arbitrary data or files, decrypt ciphertext, sign payloads, verify signatures, batch operations, and envelope encryption via Generate Data Key. All operations reference a named encryption key and are logged in the audit trail.

2. What is it for?

Encrypting sensitive data at rest

Encrypt data before storing in databases, object storage, or any persistence layer.

Protecting data in transit

Encrypt payloads sent between services so that only the intended recipient can decrypt them.

Signing messages and documents

Sign API payloads, documents, or JWT claims to prove authenticity and detect tampering.

Verifying external signatures

Verify signatures produced by external systems using a public key stored in QuantumAPI.

Batch operations

Encrypt or decrypt thousands of records in a single API call for efficient database migrations or bulk processing.

Envelope encryption

Generate a Data Encryption Key (DEK), encrypt your data locally, and have QuantumAPI wrap the DEK with your master key.

3. Key concepts

Term	Definition
Plaintext	The original data before encryption, encoded as Base64 in API requests.
Ciphertext	The encrypted output returned by the encrypt operation.
Encapsulated key	For ML-KEM operations, the key encapsulation mechanism output that allows the recipient to derive the shared secret.
Nonce	A QRNG-generated unique value used once in each encryption operation to ensure ciphertext uniqueness.
Tag (auth tag)	The authentication tag from AES-256-GCM that verifies the ciphertext has not been tampered with.
Key ID	The identifier of the encryption key to use. Defaults to the tenant's default key.
Envelope encryption	A pattern where a master key (KEK) encrypts a per-operation data key (DEK). Data is encrypted with the DEK, not the KEK directly.
DEK	Data Encryption Key — a short-lived key generated for a single encrypt operation and then wrapped with the KEK.
Batch operation	An API call that encrypts or decrypts multiple independent payloads in a single request for efficiency.
Legacy mode	A compatibility mode for interoperability with older ciphertext formats. Not recommended for new integrations.

4. How to use it

Encrypting data

Use the encrypt endpoint or CLI to encrypt arbitrary data using a named key:

Encrypt via API

POST /api/v1/encrypt
{
  "keyId": "key_abc123",
  "plaintext": "SGVsbG8gV29ybGQ="
}

Encrypt via CLI

qapi encrypt "Hello World" --key-id <key-id>

Decrypting data

Pass the full encryption response back to the decrypt endpoint:

Decrypt via API

POST /api/v1/decrypt
{
  "keyId": "key_abc123",
  "ciphertext": "...",
  "nonce": "...",
  "tag": "..."
}

Signing a payload

Sign data using an ML-DSA or SLH-DSA key:

Sign via CLI

qapi sign "payload" --key-id <key-id>

Verifying a signature

Verify a signature against the original data and the signer's public key:

Envelope encryption (Generate Data Key)

Generate a DEK wrapped by your master key, then encrypt data locally:

Generate DEK

POST /api/v1/generate-data-key
{ "keyId": "key_abc123" }
# Returns: { "plaintextDek": "...", "encryptedDek": "..." }
# Use plaintextDek to encrypt data locally, store encryptedDek alongside

5. Field reference

Request fields (encrypt)

Field	Type	Required	Description
keyId	UUID	No	Key to use. Defaults to the tenant's default key.
plaintext	Base64 string	Yes	Data to encrypt, Base64-encoded.
context	string	No	Additional authenticated data (AAD). Must be the same on decrypt.

Response fields

Field	Type	Description
ciphertext	string	Base64-encoded ciphertext.
encapsulatedKey	string	ML-KEM encapsulated key (asymmetric only).
nonce	string	QRNG-generated nonce used in this operation.
tag	string	AES-GCM authentication tag.
keyId	UUID	ID of the key used (important if default key was used).

6. Relationships

Encryption Keys

Every encrypt/decrypt operation references an encryption key by ID. Manage keys in Keys → Encryption Keys.

Transit Engine

The Transit Engine wraps these operations in a named-key model suitable for database-transparent encryption.

API Keys

An API Key with scope encrypt:invoke is required to call encrypt/decrypt endpoints.

SDKs

All official SDKs (TypeScript, Python, .NET, Rust) expose encrypt, decrypt, sign, and verify methods.

7. FAQ

What is the difference between encrypt and sign?

Encryption provides confidentiality — only the holder of the private key can decrypt. Signing provides authenticity — anyone with the public key can verify, but only the key holder can sign. Use ML-KEM for encryption and ML-DSA for signing.

Can I encrypt a file larger than 1 MB?

The API supports payloads up to 10 MB per request. For larger files, use envelope encryption: generate a DEK via the API, encrypt the file locally with the DEK, and send only the wrapped DEK to the API.

What is legacy encryption mode and when should I use it?

Legacy mode produces ciphertext compatible with older format expectations. Use it only when integrating with systems that require a specific format. For all new integrations, use the default mode.

How do I decrypt if I don't have the encapsulated key?

For ML-KEM operations, the encapsulated key is required for decryption. Store the full encrypt response (ciphertext + encapsulatedKey + nonce + tag + keyId) and never discard any field.

8. API / CLI reference

Method	Endpoint	Description
POST	/api/v1/encrypt	Encrypt data using a named key.
POST	/api/v1/decrypt	Decrypt ciphertext.
POST	/api/v1/sign	Sign a payload.
POST	/api/v1/verify	Verify a signature.
POST	/api/v1/generate-data-key	Generate and wrap a DEK for envelope encryption.
POST	/api/v1/encrypt/batch	Encrypt multiple payloads in one call.
POST	/api/v1/decrypt/batch	Decrypt multiple payloads in one call.

CLI examples

qapi encrypt "Hello World" --key-id <key-id>
qapi encrypt -k <key-id> -i plaintext.txt -o encrypted.bin
qapi decrypt -k <key-id> --ciphertext <base64> --nonce <nonce> --tag <tag>
qapi sign "payload" --key-id <key-id>
qapi verify "payload" --signature <sig> --key-id <key-id>