Skip to content
formalcoPublic

About

Reference decryptor for Formal's field-level log encryption

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

Decryptor

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.

How it works

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:

  1. parses the JWE and reads the kid;
  2. picks a provider from the URI scheme and asks it to unwrap the content key (AWS KMS Decrypt, GCP KMS AsymmetricDecrypt, or Azure Key Vault Decrypt, all RSA-OAEP-256);
  3. 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.

Password

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' ' -f1

The 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.

Deployment

The decryptor is one binary. It can run anywhere you can run a container.

Configuration

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:

Tests

go test ./... covers JWE parsing and decryption with a stubbed KMS unwrap.

About

Reference decryptor for Formal's field-level log encryption

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages