Key
A Key is an encryption key in your customer's own AWS KMS, Cloud KMS, or Azure Key Vault. Storage, databases, and volumes encrypt with it, so the customer controls whether their data can be read: the key never leaves their account, and they can revoke it at any time.
import * as alien from "@alienplatform/core"
const customerKey = new alien.Key("customer-key").build()
const files = new alien.Storage("files").encryptionKey(customerKey).build()
const api = new alien.Worker("api")
.code({ type: "source", src: "./api", toolchain: { type: "typescript" } })
.link(customerKey)
.permissions("execution")
.build()
export default new alien.Stack("acme")
.add(customerKey, "frozen")
.add(files, "frozen")
.add(api, "live")
.permissions({
profiles: { execution: { "customer-key": ["key/remote-cryptography"] } },
})
.build()In this stack:
.link(customerKey)connects the key to theapiWorker, the workload (the running code) that uses it. Alien injects the key's connection details, its binding, into the Worker, read by the SDK client.- The
executionpermission profile, the named set of cloud permissions a workload runs with, grantskey/remote-cryptography: encrypting and decrypting small values. "frozen"means the customer's admin creates the key during initial setup."live"resources, like the Worker, are created and updated by Alien on every release. See Frozen and live.
The api Worker encrypts small values with the key:
import { key } from "@alienplatform/bindings"
const ciphertext = await key("customer-key").encrypt(Buffer.from("small secret"))Platforms
customer-key becomes a key in the customer's own key service:
| Platform | Backing service | Created by |
|---|---|---|
| AWS | A symmetric KMS key, or an existing KMS key in the same account and region (Terraform setup) | Initial setup |
| GCP | A Cloud KMS key ring and an ENCRYPT_DECRYPT key | Initial setup |
| Azure | A Key Vault with an RSA 2048 key | Initial setup |
| Kubernetes | Not supported | |
| Machines | Not supported | |
| Local | Not supported |
There is no external binding for a Key.
Bring your own key
Key is the in-deployment way for a customer to bring their own key (BYOK). Revoking it makes the data it protects unreadable until they restore it. Setting it up and revoking it are covered in Customer-managed keys in a deployment.
If your product stays hosted in your cloud, use the Encrypt/Decrypt API instead. See Customer-managed keys.
Initial setup only
A Key is always "frozen": the customer's admin creates it once, during initial setup, with their own credentials. Ongoing management never creates or replaces it.
- A stack with a
Keydeploys only through the CloudFormation or Terraform setup method. - The CLI setup method, including
alien deploy, refuses it before creating anything, withSETUP_METHOD_CANNOT_INSTALL_RESOURCES. - Linking a Key grants nothing by default. Name
key/remote-cryptographyin the profile for code that encrypts or decrypts.
Key has no options besides .enabled(input).
Which resources accept a key
| Resource | Option | Platforms | What it encrypts |
|---|---|---|---|
Storage | .encryptionKey(key) | AWS, GCP, Azure | Objects. S3 uses SSE-KMS, Cloud Storage sets the bucket's default KMS key, Azure encrypts the storage account. The Storage must be "frozen". |
Postgres | .encryptionKey(key) | AWS | Aurora storage, snapshots, and Performance Insights data. |
Container | .persistentStorage(size, { encryptionKey }) | AWS | EBS volumes and their snapshots. |
encryptionKeymust be analien.Key. Anything else throwsINVALID_ENCRYPTION_KEY.- The Key must be in the same stack.
- A stack that uses a key on a platform that doesn't support it fails the build.
- On Azure, the key applies to the whole storage account, so a stack that encrypts Storage with a key can contain only one Storage.
- The key on a resource can't be added, removed, or changed after the resource exists.
Use it from code
encrypt and decrypt take up to 128 bytes and an optional context, a map of strings. Decrypt with the same context you encrypted with, or it fails.
import { key } from "@alienplatform/bindings"
const customerKey = key("customer-key")
const context = { recordType: "credential", recordId: "rec_123" }
const ciphertext = await customerKey.encrypt(Buffer.from("small secret"), { context })
const plaintext = await customerKey.decrypt(ciphertext, { context })key is exported from @alienplatform/bindings, not @alienplatform/sdk.
| Method | TypeScript | Python | Rust |
|---|---|---|---|
| Encrypt | encrypt(plaintext, { context? }) → Buffer | encrypt(plaintext, context=None) → bytes | encrypt(&[u8], Option<&BTreeMap>) → Vec<u8> |
| Decrypt | decrypt(ciphertext, { context? }) → Buffer | decrypt(ciphertext, context=None) → bytes | decrypt(&[u8], Option<&BTreeMap>) → Vec<u8> |
Put values that identify the record, such as its type and ID, in the context. A ciphertext copied to another record then fails to decrypt.
To encrypt more than 128 bytes:
- Generate a random data key.
- Encrypt your data with it locally.
- Encrypt only the data key with the Key, and store the encrypted data key next to the data.
For software you host outside the customer's cloud, publish the Key as a remote binding and call encrypt and decrypt from your backend. A remotely published Key must be the stack's only remoteAccess resource.
How values are encrypted
The SDK wraps the plaintext in a small frame: the bytes AKBF, a version byte, the plaintext length, and the SHA-256 hash of the encoded context. The frame is then encrypted by the cloud:
| Platform | Call | Context binding |
|---|---|---|
| AWS | KMS Encrypt / Decrypt | Passed as the KMS encryption context, and hashed into the frame. |
| GCP | Cloud KMS encrypt / decrypt | Passed as additional authenticated data, and hashed into the frame. |
| Azure | Key Vault encrypt / decrypt with RSA-OAEP-256 | Hashed into the frame. |
Ciphertexts are only readable through the same Key and its cloud. They aren't portable between clouds.
Errors
| Code | Retryable | When |
|---|---|---|
KEY_INPUT_INVALID | No | Plaintext over 128 bytes, or an encoded context over 16 KiB. |
KEY_CIPHERTEXT_INVALID | No | The decrypted data isn't an Alien frame, has a bad length, or the context doesn't match. |
BINDING_NOT_CONFIGURED | No | The workload isn't linked to this Key. |
Cloud failures, including a revoked key, keep the cloud error.
Rotation
| Platform | Rotation |
|---|---|
| AWS | Automatic yearly rotation is on. KMS keeps earlier key material, so earlier ciphertexts still decrypt. |
| GCP | A new primary key version every 90 days. Earlier versions stay enabled, so earlier ciphertexts still decrypt. |
| Azure | No rotation policy. Storage uses the versionless key ID, so Azure Storage follows a new key version on its own. |
Rotation keeps the same key. Replacing the key with a different one, for example a new KMS key ARN, isn't allowed on an existing deployment.
Revoke and restore
The customer can disable the key, schedule it for deletion, or remove Alien's access to it at any time.
- Alien's management identity checks the key regularly. A KMS
AccessDeniedorNotFound, or a 403 or 404 from Cloud KMS or Key Vault, marks the key unavailable, and the deployment shows Customer key unavailable. Throttling and server errors don't. - While the key is unavailable, Alien stops updating every resource that uses it. It never deletes or replaces a resource to work around a missing key.
- Each cloud service stops reading the data on its own schedule. A running Aurora cluster, for example, keeps its data key in memory for a while before it stops serving.
- Calls to
encryptanddecryptfrom code fail with the cloud's access error.
When the customer restores access, the same buckets, databases, and volumes come back with their data. On AWS, Alien restarts an Aurora cluster that stopped because of the key, using postgres/key-recovery.
Treat a revoked key as an expected state in your product: show it to the customer, and don't fall back to a copy of their data elsewhere. See Customer-managed keys in a deployment.
What initial setup creates
| AWS | GCP | Azure | |
|---|---|---|---|
| Key | Symmetric KMS key | ENCRYPT_DECRYPT key in a new key ring | RSA 2048 key with encrypt, wrapKey, and unwrapKey |
| Rotation | Yearly, automatic | Every 90 days | None |
| Deletion | 30-day pending window. CloudFormation retains the key, and Terraform refuses to destroy it. | Terraform refuses to destroy it. Cloud KMS keys can't be deleted, only their versions. | Key Vault with purge protection and 90-day soft delete. Terraform refuses to destroy it. |
| Bring your own | With Terraform, initial setup accepts <label>_existing_key: a KMS key ARN in the same account and region. Aliases aren't accepted. |
Only initial setup creates or deletes the key. Deleting the deployment leaves it in the customer's account.
Limits
| Limit | Value |
|---|---|
Plaintext per encrypt call | 128 bytes |
| Encoded context | 16 KiB |
| Key on a resource | Fixed after the resource exists |
| Azure Storage with a key | One Storage per stack |
Permissions
| Set | Grants |
|---|---|
key/remote-cryptography | Encrypting and decrypting with the key from code. |
key/native-storage | Letting a workload read and write Storage encrypted with the key. |
key/native-volume | EBS encryption with the key through EC2, including service-created grants (AWS). |
key/native-volume-management | Creating EBS volumes encrypted with the key, without decrypting (AWS). |
key/availability | Checking that the key works by encrypting a probe, without decrypting data. |
key/management | Reading key metadata for health checks and drift detection. |