Docs

AWS Virtual Keys

An AWS Virtual Key is an ordinary AWS KMS key in your account whose key material Alien serves, protected by your customer's key. It's one path of Customer-managed keys: your resources stay where they are, and the customer holds the key that makes their data readable.

An Aurora database in your own AWS account asks AWS KMS for a data key. Because that KMS key is an Alien Virtual Key, KMS sends the already-encrypted data key to Alien over the External Key Store protocol, and Alien wraps it under the key your customer connected — in AWS KMS, Google Cloud KMS, or Azure Key Vault. The resource stays in your account; only the key belongs to the customer, who can disable it at any time.

AWS services already encrypt with KMS. A Virtual Key gives them a normal key ARN to point at, while Alien serves the key material through AWS KMS External Key Store (XKS):

  1. Aurora, S3, or EBS asks AWS KMS for a data key, as it always does.
  2. AWS KMS sends the data key, already encrypted by AWS, to Alien over XKS.
  3. Alien wraps it under the key your customer connected.

Aurora, your application, and your Terraform see nothing unusual.

What the customer gets

  • Their key can be anywhere. It can live in AWS KMS, Google Cloud KMS, or Azure Key Vault. A customer on Azure Key Vault can govern the Aurora database you run for them.
  • Plaintext never reaches Alien. AWS encrypts the data key before sending it, so Alien receives and returns ciphertext.
  • Revocation is final if they want it. Neither AWS nor Alien can decrypt alone, which AWS calls double encryption. If the customer permanently revokes their key, the data can't be recovered.

Nothing moves into the customer's cloud. When they need your code itself running in their environment, see Control plane ⇄ Data plane.

Create the key

A Virtual Key belongs to one customer's key connection. Read its ID as keys.deploymentId from the capability overview, then run the module from the AWS Virtual Key tab on the Customer-managed keys page:

main.tf
module "customer_key" {
  source  = "pkg.alien.dev/alien/virtual-key/aws"
  version = "0.1.0"

  deployment_id = "dep_0c29fq4a2yjb7kx3smwdgxlc" # the customer's key connection
  alias         = "customer-1-documents"
}

output "kms_key_arn" {
  value = module.customer_key.kms_key_arn
}

Run Terraform or OpenTofu with credentials for your AWS account, and an Alien API key in ALIEN_API_KEY. The module uses the AWS credential chain and region from the environment.

The module also outputs kms_key_id, custom_key_store_id, and virtual_key_id.

Point a resource at it

Pass the key ARN to any AWS resource that takes a customer-managed KMS key:

main.tf
resource "aws_s3_bucket_server_side_encryption_configuration" "documents" {
  bucket = aws_s3_bucket.documents.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = module.customer_key.kms_key_arn
    }
  }
}

DynamoDB and EBS take the same ARN. Your application doesn't call /v1/encrypt for these resources.

Latency

The key is on the encryption path, so distance matters. AWS recommends 35 ms or less of round-trip time between the Region and the external key store.

AWS services don't call KMS per row or per object. Aurora, S3, and EBS request a data key and reuse it, so the XKS round trip happens at resource start and failover, not on every read.

Rotate and delete

  • Rotate the XKS credential. Increment credential_generation by one and apply. Alien accepts both generations while AWS KMS updates, then retires the old one. The secret never enters Terraform state.
  • Delete the key. Deletion protection is on by default. Set deletion_protection = false and apply, then destroy.
  • Deletion window. Destroy disables the KMS key and schedules deletion after deletion_window_days (7 to 30, default 30). Alien stops serving its key material.
  • Permissions. Destroy needs a workspace admin key, or a project key with the project admin role (alien api-keys create --for project-admin).

Limits

  • The resource must be in AWS: Virtual Keys rely on AWS KMS XKS. The customer's key can be in any of the three clouds.
  • For a single-tenant deployment that Alien runs in your AWS account, pick the customer's key at launch instead.

Next

Add to your product

Build a Customer-managed keys settings page into a product you host. The customer connects a key in their cloud; your backend encrypts through the Encrypt/Decrypt API.

In a deployment

Encrypt a deployment's storage, databases, and volumes with a key the customer owns and can revoke, using alien.Key in alien.ts.

On this page

What the customer getsCreate the keyPoint a resource at itLatencyRotate and deleteLimitsNext