Encryption Keys

Manage encryption keys

Overview

Encryption keys let you encrypt sensitive fields in logs and sessions before they reach Formal’s servers. You decrypt them on demand from your browser.

Encrypted fields are stored in a formalencrypt:... format instead of plaintext. Refer to the log configuration documentation to learn which fields can be encrypted.

Configuration via Terraform

Encryption keys are managed through the formal_encryption_key resource. Only AWS KMS is supported today.

provider "aws" {
  region = "us-east-1"
}

resource "aws_kms_key" "formal_logs_key" {
  description = "KMS key for Formal logs encryption"
}

resource "formal_encryption_key" "logs_key" {
  key_provider = "aws"
  key_id       = aws_kms_key.formal_logs_key.arn
  algorithm    = "aes_deterministic"
  # Optional: an HTTPS endpoint the browser calls to decrypt individual fields.
  # decryptor_uri = "<HTTPS endpoint to perform decryption>"
}

The region is derived from the key ARN, so pass the full ARN in key_id.

Available Algorithms

Symmetric keys (aes_random, aes_deterministic) cannot encrypt client side, so the Desktop App ignores them. Use rsaes_oaep_sha256 for Desktop App logs.

AES-256 Random (aes_random)

aes_random uses probabilistic encryption. The same plaintext produces different ciphertexts, so identical values cannot be correlated. This gives the strongest guarantees but prevents search.

AES-256 Deterministic (aes_deterministic)

aes_deterministic uses deterministic encryption. The same plaintext always produces the same ciphertext. Users can tell whether two values are identical and search by frequency, without learning the original value.

RSA-OAEP (rsaes_oaep_sha256)

rsaes_oaep_sha256 uses asymmetric encryption. Use it when the party encrypting data has no AWS credentials, such as the Formal Desktop App. The encrypting client holds only the public key; only your decryptor can recover the plaintext.

This algorithm requires an asymmetric KMS key and its public key in PEM format:

resource "aws_kms_key" "formal_desktop_key" {
  description              = "Asymmetric key for Formal Desktop App log encryption"
  customer_master_key_spec = "RSA_4096"
  key_usage                = "ENCRYPT_DECRYPT"
}

data "aws_kms_public_key" "formal_desktop_key" {
  key_id = aws_kms_key.formal_desktop_key.id
}

resource "formal_encryption_key" "desktop_key" {
  key_provider   = "aws"
  key_id         = aws_kms_key.formal_desktop_key.arn
  algorithm      = "rsaes_oaep_sha256"
  public_key_pem = data.aws_kms_public_key.formal_desktop_key.public_key_pem
  decryptor_uri  = "<HTTPS endpoint to perform decryption>"
}

The Decryptor

Formal cannot decrypt these fields. When you set a decryptor_uri, the client-side JavaScript of the Formal Console calls it when a user decrypts a field. The endpoint must support CORS and accept POST requests with the encrypted payload in the body. Use this decrypt-lambda reference implementation.

The decryptor has no authentication between the Formal console and the decryptor lambda. For security, deploy it behind a VPN or private network to restrict access.