Reference and how-to

Referential Integrity with Valkey

How to configure a Valkey cache so Philter maintains referential integrity (consistent replacement values) across documents and contexts in a cluster.

The referential integrity feature in Philter ensures that filtered values are replaced consistently across documents or contexts. When Philter is deployed in a cluster and is using referential integrity across contexts, a Valkey cache is required. The cache stores the replacement values so that all instances of Philter have access to the same replacement values for the same original values.

The Valkey cache will contain PHI. It is important to prepare your Valkey cache such that it can contain PHI.

Configuring the Valkey cache

To enable Philter to use the Valkey cache, set the following properties. Philter reads each one from an environment variable or Java system property of the same name, or from philter.properties.

Property	Description	Default Value
`cache.enabled`	Set to `true` to use the Valkey cache.	`false`
`cache.host`	The hostname or IP address of the Valkey cache.	`127.0.0.1`
`cache.port`	The Valkey port.	`6379`
`cache.auth.token`	The Valkey password.	(empty)
`cache.ssl`	Whether to use TLS for communication with the Valkey cache.	`false`

If you are using Valkey on AWS ElastiCache, see ElastiCache for Valkey In-Transit Encryption (TLS) for information on using in-transit encryption.

Protect the cache like the database

Philter reads replacement values from the cache, so anyone who can write to it can change what Philter writes into redacted documents, and anyone who can read it can see what is cached. Treat the Valkey cache with the same care as Philter’s database:

Require a password and set cache.auth.token on every Philter instance.
Set cache.ssl to true unless the cache is reachable only on a private network.
Allow only Philter’s instances to connect to the cache, for example with security groups or a private network.

Restart Philter

After starting (or restarting) Philter, it will use the Valkey cache for referential integrity across contexts.

Coming in Philter 4.0

Philter 4.0 changes how the cache is used and protected:

The settings are renamed. Philter 4.0 is configured with the environment variables CACHE_HOSTNAME, CACHE_PORT (default 6379), CACHE_PASSWORD, and CACHE_SSL, in place of the cache.* properties above.
Valkey is optional for a single instance. When CACHE_HOSTNAME is not set, Philter uses an in-memory cache. Valkey is required when more than one instance shares a database, and every instance must use the same Valkey.
What Philter stores in Valkey is encrypted. Each value is encrypted and authenticated under a key derived from PHILTER_ENCRYPTION_KEY, and key names are hashed, so the cache does not show API keys, user IDs, context names, or replacement values. A value that Philter did not write is ignored, and Philter reads the database instead. Every instance sharing the cache must use the same PHILTER_ENCRYPTION_KEY.
Philter warns about an unprotected cache. At startup, Philter logs a warning when the cache is on another host and has no password or does not use TLS.

Encryption does not replace access control: anything that can reach the cache can still delete entries. Protect it as described above. See Caching in the Philter documentation for details.

Philter is part of Philterd’s open source PII redaction software toolkit.