Customer-managed keys
Customer-managed keys (bring your own key, or BYOK) let a customer hold the key that makes their data readable, in their own cloud. Your product keeps storing and serving the data, and the customer can cut off access at any time, without your help. Your product can keep running in your cloud, shared or dedicated to them: only the key sits in theirs.
Data reaches Alien three ways: your backend calling the Encrypt/Decrypt API, a Key attached to a resource in alien.ts, or an AWS resource using a Virtual Key through KMS. All three use one encryption root, protected by the AWS, Google Cloud, or Azure key the customer connected.
The key lives in the customer's AWS KMS, Google Cloud KMS, or Azure Key Vault. Your application never receives their cloud credentials or the raw key material.
Alien runs the Encrypt/Decrypt API at encryption.alien.dev, which encrypts with each customer's key. The Encrypt/Decrypt API and AWS Virtual Keys both end at the same place: an encryption root protected by the key that customer connected.
Pick a path
Which path fits depends on what holds the data:
| If the data lives in | Use | What your application changes |
|---|---|---|
| Fields your application stores and never queries by | Encrypt/Decrypt API | Calls Alien before writing and after reading |
| A database or bucket you query | A key on the whole resource | Nothing: the resource uses an ordinary KMS key |
BYOK combines with any deployment. A common setup is a single-tenant data plane in your cloud, encrypted with the customer's key.
Encrypt application records
Your backend sends a value to the Encrypt/Decrypt API with the customer's external ID, your own stable ID for that customer. Alien encrypts it under that customer's key and returns ciphertext you store as before.
const res = await fetch("https://encryption.alien.dev/v1/encrypt", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALIEN_ENCRYPTION_API_KEY}`,
"X-Alien-External-ID": customer.id, // whose key protects the value
"Content-Type": "application/json",
},
body: JSON.stringify({
key: { keyId: "customer-data" }, // the cryptographic context
plaintext: Buffer.from(value).toString("base64"),
}),
})
const { ciphertext } = await res.json()Use it for fields, documents, credentials, and other data your application stores itself. The customer connects their key once, from a settings page in your product: see Add to your product.
Search, sort, and indexes
Field-level encryption has one cost: your database stores ciphertext, so it can't filter, sort, join, or index on an encrypted field. A WHERE email = ..., an ORDER BY, a range query, or a full-text or vector index on that field stops working.
- Encrypt fields you never query by. Message bodies, documents, notes, and credentials fit. Keep IDs, timestamps, and status in plaintext.
- Encrypt the whole resource for everything else. The database or bucket encrypts at rest with a key backed by the customer's key, and every query keeps working. See Encrypt whole resources.
A database or bucket has one key. To use each customer's key on a whole resource, each customer needs their own copy of it: a single-tenant setup for the stateful part of your product. Alien deploys that part as a stack, the same one that can later run in the customer's own cloud with BYOC.
Encrypt whole resources
Nothing passes through the Encrypt/Decrypt API on these paths. Pick one by where the resource runs:
An AWS Virtual Key is an ordinary AWS KMS key in your account, backed by the customer's key. Aurora, S3, DynamoDB, or EBS use its ARN like any KMS key, and your application keeps using the AWS SDK.
- Their key can be in AWS KMS, Google Cloud KMS, or Azure Key Vault.
- Plaintext never reaches Alien on this path.
See AWS Virtual Keys.
Latency
Encryption sits in the path of every read and write of a protected field, so its cost stays small:
- Alien loads a customer's encryption root through their key service once, then caches it for 5 minutes.
- While the root is cached, encrypt and decrypt run inside Alien with AES-256-GCM, without calling the customer's cloud.
- Your steady-state cost is one HTTPS round trip to Alien, not a round trip to the customer's key service.
The same cache is why revocation takes up to 5 minutes. AWS Virtual Keys work differently: AWS services fetch a data key and reuse it, so the cost lands at resource start, not on every query.
Revoking the key
- The customer disables the key in their cloud console.
- Within minutes, requests that need the key fail. Your app gets a
KEY_UNAVAILABLEerror, and a deployment shows Customer key unavailable. - Resources are kept. Alien pauses changes to anything that depends on the key and never replaces those resources.
- When the customer re-enables the key, the same resources recover with their data.
Revoking doesn't delete ciphertext you already stored. Each cloud service stops reading the data on its own schedule:
- In AWS tests, the app reported the key unavailable about 5 minutes after it was disabled, and recovered without data loss after it was re-enabled.
- A running Aurora cluster stopped serving after about 26 minutes, because a running database keeps its data key in memory for a while.
Decide in advance what your product shows a customer whose key is revoked, and never fall back to a copy of their data elsewhere.
Connect a key
The customer connects the key once, from a setup link or a settings page in your product, on the Bring your own key card:
- They choose a cloud.
- They run a CloudFormation stack (AWS) or Terraform module (AWS, Google Cloud, Azure) that grants encrypt and decrypt on one key.
Your team never handles the key, and Alien never receives the raw key material. See Add to your product.
What crosses
| Path | What reaches your cloud or Alien |
|---|---|
| Encrypt/Decrypt API | The plaintext of each field, on its way through the Encrypt/Decrypt API |
| AWS Virtual Key or single-tenant deployment | The data itself, in your cloud, encrypted at rest under the customer's key |
| A deployment in the customer's cloud | Nothing. The resources encrypt at rest in the customer's cloud. |
A key lets the customer revoke access. It doesn't keep content out of your cloud. When the buyer says their data can't leave their account, the code that touches it belongs in a data plane in their cloud, which can still use their key. See Data and keys.