Skip to content

redis.md

Latest commit

 

History

History
122 lines (88 loc) · 5.58 KB

redis.md

File metadata and controls

122 lines (88 loc) · 5.58 KB
Raw

Redis with Findex

The KMS can store its entire database in Redis using the Redis-with-Findex backend. Redis-with-Findex combines application-level encryption with encrypted, searchable indexes, so the KMS can query encrypted data without revealing it to the Redis server.

!!! warning "Non-FIPS only" Redis-with-Findex is gated behind the non-fips feature and is not available in FIPS mode.

Configuration

Redis-with-Findex requires the database URL and a master password:

=== "kms.toml"

```toml
[db]
database_type = "redis-findex"
database_url = "redis://localhost:6379"
redis_master_password = "password"
redis_findex_label = "label"
```

=== "Command line arguments"

```sh
--database-type=redis-findex \
--database-url=redis://localhost:6379 \
--redis-master-password=password \
--redis-findex-label=label
```

The corresponding environment variables are KMS_DATABASE_TYPE, KMS_DATABASE_URL (also KMS_REDIS_URL), KMS_REDIS_MASTER_PASSWORD, and KMS_REDIS_FINDEX_LABEL.

For the full database configuration reference, including TLS, clearing, and migration, see Databases.

!!! note "Clearing the database" When clear_database is set, the KMS issues a FLUSHDB to Redis on startup, deleting all keys in the selected Redis database.

What it is

With Redis-with-Findex, the KMS server encrypts all data before sending it to Redis:

  • Objects and permissions are encrypted with AES-256-GCM using a key derived from a master password.
  • Indexes are built with Findex, an Eviden cryptographic algorithm that produces encrypted indexes over encrypted data. The indexes are also stored in Redis, allowing fast encrypted queries (for example Locate by tag or attribute) without the KMS ever sending plaintext to Redis.

Redis-with-Findex provides post-quantum resistance on both the encrypted data and the encrypted indexes.

When to use it

Redis-with-Findex is most useful when:

  • The KMS servers run inside a confidential VM or an enclave. In this case the secret used to encrypt the Redis data and indexes is protected by the VM or enclave and cannot be recovered at runtime by inspecting the KMS servers' memory.
  • The KMS servers are run by a trusted party, but the Redis backend is managed by an untrusted third party.

It is the database selected to run the Eviden KMS in the cloud or any other zero-trust environment.

How encryption keys are derived

  1. A master password is provided at startup (redis_master_password).
  2. A 32-byte master key is derived from the password using Argon2 (salt rediswithfindex_).
  3. A database key is derived from the master key (salt db) and is used to encrypt the object and permission data with AES-256-GCM.
  4. The master key is also used by the Findex encryption layer to encrypt the searchable indexes.

The master password never leaves the KMS server; only the derived keys are used in memory.

Connection & Operation Workflow

The sequence diagram below shows how the Eviden KMS connects to Redis, initializes cryptographic keys in memory, and performs encrypted storage and indexing operations:

sequenceDiagram
    autonumber
    actor Client as KMS Client (CLI / REST / KMIP)
    participant KMS as Eviden KMS Server (Enclave / Confidential VM)
    participant Findex as Cosmian Findex Engine
    participant Redis as Redis Server (Remote / Untrusted)

    Note over KMS,Redis: Startup & In-Memory Key Derivation
    KMS->>KMS: Derive Master Key via Argon2 (salt: rediswithfindex_)
    KMS->>KMS: Derive Database Key via Master Key (AES-256-GCM)
    KMS->>Redis: TCP / TLS Connect & AUTH
    Redis-->>KMS: Connection established
    KMS->>Redis: Check metadata keys (db_state, db_version)
    Redis-->>KMS: State: ready

    Note over Client,Redis: Storing an Object (e.g. Create Key)
    Client->>KMS: Create AES key request
    KMS->>KMS: Encrypt object data with DB Key (AES-256-GCM)
    KMS->>Findex: Generate encrypted search tokens for tags & attributes
    Findex-->>KMS: Encrypted index entries
    KMS->>Redis: SET encrypted object by UID & update Findex keys
    Redis-->>KMS: OK (Redis never sees plaintext key material or search terms)
    KMS-->>Client: Key created (returns UID)
Loading

Data layout in Redis

Redis-with-Findex does not use relational tables (see Database tables for the SQL schema). Instead it stores:

Data Storage
Objects AES-256-GCM encrypted values, keyed by object UID
Permissions Encrypted, indexed through Findex
Searchable indexes Findex encrypted indexes (Redis is used as the Findex memory layer)
Database metadata Internal keys holding the database state (ready/upgrading) and version
Ceremony records Encrypted records under key names obfuscated with the master key

Migration

Version boundary: Redis-with-Findex databases created with KMS 5.12.0 or later carry a ready state marker and a version key in Redis, and start cleanly with the current KMS (5.26). Databases created with KMS earlier than 5.12.0 do not have these markers. The KMS refuses to start against a marker-less database and prints an error asking you to export and re-import; there is no in-place upgrade path for those databases.

Supported upgrade paths:

Source version Path to 5.26
≥ 5.12 Upgrade directly; no data migration needed.
< 5.12 Export all objects from the old KMS, start a fresh 5.26 instance, re-import.