Skip to main content

​
Overview

Encryption keys in Formal allow you to encrypt sensitive data in logs and sessions when storing these data in Formal’s servers. You can decrypt it when viewing the data from your browser. Certain log fields, instead of being plaintext, will be encrypted in a format like “formalencrypt:_____”. Refer to the log configuration documentation to learn more about which fields are able to be encrypted.

​
Configuration via Terraform

Encryption keys are managed through the formal_encryption_key resource in Terraform. Currently, only AWS KMS is supported as a provider: 
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.id
  region       = "eu-west-1"
  algorithm    = "aes_deterministic"
  # Optionally specify a decryptor_uri that the browser can use for attempting to decrypt individual log fields.
  # decryptor_uri = "<HTTPS endpoint to perform decryption>"
}
When creating an encryption key, you can choose between two algorithms:

​
AES-256 Random

The aes_random setting will use probabilistic encryption, which provides stronger guarantees than determinstic encryption. In particular, the same plaintext will produce different ciphertexts, so there will be no ability to correlate identical data. This does limit searchability, however.

​
AES-256 Deterministic

The aes_deterministic setting will use deterministic encrpytion, which means that the same plaintext will produce the same ciphertext. This means that users can learn whether two plaintexts are identical and thus perform searches for the frequency of certain data even if users cannot easily determine what the original was.

​
The Decryptor

Formal will not be able to decrypt these data. When creating an encryption key, you can also specify a decryptor URI. If present, this decryptor URI will be called from https://app.joinformal.com when a user tries to decrypt certain log fields in their browser. This decryptor URI should support CORS and serve POST requests where the encrypted payload is passed in the request body. Use this decrypt-lambda reference implementation.
The decryptor does not have authentication between the Control Plane UI and the decryptor lambda. For security, deploy the decryptor behind a VPN or private network to restrict access.