Docs

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.

alien.ts
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 the api Worker, 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 execution permission profile, the named set of cloud permissions a workload runs with, grants key/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:

api/src/seal.ts
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:

PlatformBacking serviceCreated by
AWSA symmetric KMS key, or an existing KMS key in the same account and region (Terraform setup)Initial setup
GCPA Cloud KMS key ring and an ENCRYPT_DECRYPT keyInitial setup
AzureA Key Vault with an RSA 2048 keyInitial setup
KubernetesNot supported
MachinesNot supported
LocalNot 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 Key deploys only through the CloudFormation or Terraform setup method.
  • The CLI setup method, including alien deploy, refuses it before creating anything, with SETUP_METHOD_CANNOT_INSTALL_RESOURCES.
  • Linking a Key grants nothing by default. Name key/remote-cryptography in the profile for code that encrypts or decrypts.

Key has no options besides .enabled(input).

Which resources accept a key

ResourceOptionPlatformsWhat it encrypts
Storage.encryptionKey(key)AWS, GCP, AzureObjects. 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)AWSAurora storage, snapshots, and Performance Insights data.
Container.persistentStorage(size, { encryptionKey })AWSEBS volumes and their snapshots.
  • encryptionKey must be an alien.Key. Anything else throws INVALID_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.

src/seal.ts
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.

MethodTypeScriptPythonRust
Encryptencrypt(plaintext, { context? }) → Bufferencrypt(plaintext, context=None) → bytesencrypt(&[u8], Option<&BTreeMap>) → Vec<u8>
Decryptdecrypt(ciphertext, { context? }) → Bufferdecrypt(ciphertext, context=None) → bytesdecrypt(&[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:

  1. Generate a random data key.
  2. Encrypt your data with it locally.
  3. 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:

PlatformCallContext binding
AWSKMS Encrypt / DecryptPassed as the KMS encryption context, and hashed into the frame.
GCPCloud KMS encrypt / decryptPassed as additional authenticated data, and hashed into the frame.
AzureKey Vault encrypt / decrypt with RSA-OAEP-256Hashed into the frame.

Ciphertexts are only readable through the same Key and its cloud. They aren't portable between clouds.

Errors

CodeRetryableWhen
KEY_INPUT_INVALIDNoPlaintext over 128 bytes, or an encoded context over 16 KiB.
KEY_CIPHERTEXT_INVALIDNoThe decrypted data isn't an Alien frame, has a bad length, or the context doesn't match.
BINDING_NOT_CONFIGUREDNoThe workload isn't linked to this Key.

Cloud failures, including a revoked key, keep the cloud error.

Rotation

PlatformRotation
AWSAutomatic yearly rotation is on. KMS keeps earlier key material, so earlier ciphertexts still decrypt.
GCPA new primary key version every 90 days. Earlier versions stay enabled, so earlier ciphertexts still decrypt.
AzureNo 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.

  1. Alien's management identity checks the key regularly. A KMS AccessDenied or NotFound, 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.
  2. 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.
  3. 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.
  4. Calls to encrypt and decrypt from 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

AWSGCPAzure
KeySymmetric KMS keyENCRYPT_DECRYPT key in a new key ringRSA 2048 key with encrypt, wrapKey, and unwrapKey
RotationYearly, automaticEvery 90 daysNone
Deletion30-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 ownWith 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

LimitValue
Plaintext per encrypt call128 bytes
Encoded context16 KiB
Key on a resourceFixed after the resource exists
Azure Storage with a keyOne Storage per stack

Permissions

SetGrants
key/remote-cryptographyEncrypting and decrypting with the key from code.
key/native-storageLetting a workload read and write Storage encrypted with the key.
key/native-volumeEBS encryption with the key through EC2, including service-created grants (AWS).
key/native-volume-managementCreating EBS volumes encrypted with the key, without decrypting (AWS).
key/availabilityChecking that the key works by encrypting a probe, without decrypting data.
key/managementReading key metadata for health checks and drift detection.

Next

On this page