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 as JWE (JSON Web Encryption) instead of plaintext. Refer to the log configuration documentation to learn which fields can be encrypted.

Log encryption keys are separate from Token Encryption. Use token encryption (and the HTTP encrypt / decrypt policy actions) to seal OAuth tokens in the data path. See Encrypt MCP OAuth Tokens.

Configuration via Terraform

Encryption keys are managed through the formal_encryption_key resource. AWS KMS, GCP KMS, and Azure Key Vault are supported, all using an asymmetric RSA key. The encrypting client (Connector or Desktop App) holds only the public key and needs no cloud credentials, so only the decryptor can recover the plaintext.

AWS KMS
GCP KMS
Azure Key Vault

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

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

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

resource "formal_encryption_key" "logs_key" {
  key_provider   = "aws-kms"
  key_id         = aws_kms_key.formal_logs_key.arn
  public_key_pem = data.aws_kms_public_key.formal_logs_key.public_key_pem
  # 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.

provider "google" {
  project = "my-project"
}

resource "google_kms_key_ring" "formal" {
  name     = "formal-logs"
  location = "us-east1"
}

resource "google_kms_crypto_key" "formal_logs_key" {
  name     = "formal-logs-key"
  key_ring = google_kms_key_ring.formal.id
  purpose  = "ASYMMETRIC_DECRYPT"

  version_template {
    algorithm = "RSA_DECRYPT_OAEP_4096_SHA256"
  }
}

data "google_kms_crypto_key_version" "formal_logs_key" {
  crypto_key = google_kms_crypto_key.formal_logs_key.id
}

resource "formal_encryption_key" "logs_key" {
  key_provider   = "gcp-kms"
  key_id         = data.google_kms_crypto_key_version.formal_logs_key.name
  public_key_pem = data.google_kms_crypto_key_version.formal_logs_key.public_key[0].pem
  # Optional: an HTTPS endpoint the browser calls to decrypt individual fields.
  # decryptor_uri = "<HTTPS endpoint to perform decryption>"
}

For GCP, pass the crypto key version resource name (projects/.../cryptoKeyVersions/N) in key_id.

resource "azurerm_key_vault_key" "formal_logs_key" {
  name         = "formal-logs-key"
  key_vault_id = azurerm_key_vault.example.id
  key_type     = "RSA"
  key_size     = 4096

  key_opts = [
    "decrypt",
    "encrypt",
  ]
}

resource "formal_encryption_key" "logs_key" {
  key_provider   = "azure-key-vault"
  key_id         = azurerm_key_vault_key.formal_logs_key.id
  public_key_pem = azurerm_key_vault_key.formal_logs_key.public_key_pem
}

Use an RSA key with ENCRYPT/DECRYPT and RSA-OAEP-256. key_id is the Key Vault key URI, either versioned (https://{vault}.vault.azure.net/keys/{name}/{version}) or versionless (https://{vault}.vault.azure.net/keys/{name}, which resolves to the key’s current version).Prefer the versioned URI. A versionless one stops decrypting fields sealed before a key rotation, because the wrapped content key only opens with the version that was current when the field was sealed. With the versioned URI, rotating the key registers a new encryption key and leaves older fields readable.

Symmetric and deterministic algorithms (aes_random, aes_deterministic) are deprecated and can no longer be registered. Encryption keys use asymmetric RSA (rsaes_oaep_sha256), which both the Connector and Desktop App can use without cloud credentials.

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 decryptor reference implementation, which unwraps AWS KMS, GCP KMS, and Azure Key Vault keys and ships Terraform examples for Lambda, Cloud Run, and Container Apps.

There is no authentication mechanism between the Formal Console and the decryptor. Deploy it behind a VPN or in a private network to restrict access.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Encryption Keys

Overview

Configuration via Terraform

The Decryptor

​Overview

​Configuration via Terraform

​The Decryptor

Overview

Configuration via Terraform

The Decryptor