Reference decryptor for Formal's field-level log encryption. Formal encrypts sensitive log fields client-side and never holds or access the private key, so you deploy this service in your own infrastructure to let users decrypt those fields on demand from their browser.
Once deployed, use the endpoint URL as the decryptor_uri on a Formal encryption key.
Note: we highly encourage making sure the endpoint is only accessible via a VPN to prevent users outside of your organization from making requests to the /decrypt endpoint.
Encrypted fields are JWE compact tokens (alg=RSA-OAEP-256, enc=A256GCM): a fresh AES-256-GCM content key is wrapped per record with the RSA public half of your KMS key. The JWE kid is a key URI of the form <scheme>://<keyID>, e.g. aws-kms://arn:aws:kms:us-east-1:123456789012:key/abcd, gcp-kms://projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1, or azure-key-vault://https://myvault.vault.azure.net/keys/formal-logs.
The Formal Console calls the decryptor from the user's browser: it POSTs the JWE token as the raw request body to your decryptor_uri and reads back {"message": "<plaintext>"}.
For each request the decryptor:
- parses the JWE and reads the
kid; - picks a provider from the URI scheme and asks it to unwrap the content key (AWS KMS
Decrypt, GCP KMSAsymmetricDecrypt, or Azure Key VaultDecrypt, all RSA-OAEP-256); - decrypts the content with the unwrapped key and returns the plaintext.
The decryptor holds no private key material; only the KMS unwrap can recover the content key.
Set DECRYPTOR_PASSWORD_SHA256 to require a password on every /decrypt request. It holds the hex-encoded SHA-256 of the password, not the password itself, so the plaintext never sits in your deployment config:
printf %s 'your-password' | shasum -a 256 | cut -d' ' -f1The decryptor refuses to start if the value isn't a 64-character hex digest. The Formal Console prompts users for it the first time a decrypt is rejected, sends it in the X-Decryptor-Password header, and keeps it in memory for the browser session. Requests without the right password get 401. Without the variable, anyone who can reach the endpoint can decrypt.
The decryptor is one binary. It can run anywhere you can run a container.
| Variable | Description | Default |
|---|---|---|
FORMAL_CONTROL_PLANE_URL |
Formal Console origin the browser may call the decryptor from. Set it to your console's origin, e.g. https://formal.example.com, for a self-hosted control plane. Must be a lowercase https origin with no path or trailing slash; the decryptor refuses to start otherwise. |
https://app.formal.ai |
DECRYPTOR_PASSWORD_SHA256 |
Hex SHA-256 of the password every /decrypt request must carry in the X-Decryptor-Password header; see Password. Unset leaves the endpoint unauthenticated. |
none |
PORT |
Listen port when running as an HTTP server | 8080 |
The root Dockerfile builds an image that runs as a standalone HTTP server or a Lambda function.
The deploy/ directory has a few examples:
- AWS Lambda via Terraform
- AWS Lambda via Serverless
- GCP Cloud Run via Terraform
- Azure Container Apps via Terraform
go test ./... covers JWE parsing and decryption with a stubbed KMS unwrap.