Data and keys

This page explains what each path of Customer-managed keys sends to Alien, and what a revoked key does. Use it for security reviews and for your product's behavior when a key is gone.

Encrypt/Decrypt APICopy Anchor Link

BYOK doesn't mean Alien never handles plaintext. Your backend sends plaintext to encrypt, and Alien returns plaintext on decrypt.

• The customer's key protects the encryption root, the secret Alien encrypts their data with.
• Raw key material is never returned to your application.
• Values are encrypted with AES-256-GCM.

Each ciphertext is bound to its cryptographic context:

• the Alien workspace and project;
• the customer's key connection, selected by external ID or deployment ID;
• the keyId;
• the optional associatedData.

Decrypting with any part changed fails with DECRYPTION_FAILED.

AWS Virtual KeysCopy Anchor Link

With an AWS Virtual Key, your AWS resource talks to AWS KMS, and AWS KMS calls Alien through XKS.

AWS encrypts the data key with its own key material before sending it. Alien receives ciphertext and returns ciphertext, and never handles plaintext on this path.

RevocationCopy Anchor Link

Alien caches a loaded encryption root for 5 minutes. After a revoke, requests can keep using the cached root until it expires:

first request       Alien loads the root through the customer's key
next five minutes   requests may use the cached root
cache expires       Alien asks the customer's key service again
access disabled     that reload fails with KEY_UNAVAILABLE

• Revoking doesn't delete ciphertext. It stays in your storage, unreadable while the key is unavailable.
• Restoring access makes the same ciphertext readable again.
• If the customer deletes the key permanently, the data can't be recovered.

Design and test your product for this state. Don't describe revocation as instant, as deletion, or as permanent.

By pathCopy Anchor Link

Your applicationCopy Anchor Link

• Keep the encryption API key in server-side secret storage, only on the service that encrypts and decrypts.
• Derive the external ID from the authenticated account on your backend, never from browser input.
• Use stable, deliberate keyId values. A changed keyId can't decrypt existing ciphertext.
• Store ciphertext, not plaintext, after encryption.
• Don't log plaintext, decrypted values, API keys, or customer credentials.
• On KEY_UNAVAILABLE, show the customer the state. Never fall back to an unencrypted copy.

NextCopy Anchor Link

• Add to your product: errors, limits, and the states your settings page shows
• Customer-managed keys: what crosses into your cloud for each design