Enterprise Deployment Guide

Secrets & Security

Manage credentials securely across environments, from environment variables to the Rescile Vault's Zero-Knowledge system and hardware TPM support.

Edit this page on GitHub

Secrets Management & Security

Rescile provides multiple layers of secret management depending on your deployment model and security requirements.

Secret Management by Deployment Model

Community Edition (rescile-ce)

Credentials for Data Generators and custom proxy apps can be resolved via environment variables. Ensure these are securely injected via your CI runner or secret manager (e.g., HashiCorp Vault, AWS Secrets Manager).

Use template expansion to pass secrets as arguments to generators rather than hardcoding them in TOML files:

[generators.discovery]
env = ["API_TOKEN={{ env.MY_SECRET_TOKEN }}"]

Enterprise Edition (rescile-portal)

In the Enterprise Edition, secrets are managed securely at the workspace level. The platform securely injects them into the execution sandbox through the same template expansion mechanism.

Rescile Vault: Zero-Knowledge Secret Management

The Rescile Vault is a Zero-Knowledge, End-to-End Encrypted (E2EE) secret management solution. While standard external vaults (like HashiCorp Vault) are excellent for runtime storage, bootstrapping access to them securely often requires a “vault for the vault”. Rescile Vault solves this bootstrapping challenge using a Zero-Knowledge Invite Token Pattern.

The Community Edition (rescile-ce) bundles both the Vault Server and the Vault Client into a single binary, making it easy to test and orchestrate secure pre-provisioning workflows.

Enterprise Hardware Security (TPM)

While rescile-ce vault is ideal for software-based environments, pipelines, and evaluation, highly secure production environments often require hardware-backed key protection.

As part of the Rescile Enterprise platform, the dedicated, standalone rescile-vault CLI client offers native TPM (Trusted Platform Module) support. When using the enterprise client, the machine’s local private keys and session secrets can be hardware-bound to the TPM enclave, ensuring that the vault identity cannot be exfiltrated from the physical server even if the root filesystem is compromised.

The standalone rescile-vault binary can be used interchangeably with rescile-ce vault, but it additionally includes native TPM support, an embedded Web UI, and a batch execution mode.

Enabling the Vault Server

By default, the vault server is disabled. To enable it, pass the --vault flag pointing to a JSON state file when starting the serve command. If the file does not exist, it will be initialized automatically.

rescile-ce --vault vault.json serve

The vault API will now be available at http://localhost:7600/vault.

Using the Vault Client

You can interact with the running vault server using the built-in client wrapper rescile-ce vault or the standalone rescile-vault binary. Both share the exact same syntax.

The client automatically handles key derivation, local encryption/decryption, and session management. It relies on environment variables for authentication:

  • RESCILE_VAULT_URL: The Vault server URL (defaults to http://localhost:7600).
  • RESCILE_VAULT_CLIENTNAME: Your identity/client name. If omitted, it defaults to $USER@$HOSTNAME (or just the hostname for root/admin users).
  • RESCILE_VAULT_PASSWORD: Your local master password. If omitted, an auto-generated password is saved to and read from /etc/rescile/vault.password (for root) or ~/.config/rescile/vault.password (for standard users).
  • RESCILE_VAULT_TPM: Set to true (or use the --tpm CLI flag) to use the hardware TPM for key protection instead of a master password (requires the standalone binary with the tpm feature enabled).

Note: Keys are derived locally. The server never sees your plaintext password or cryptographic material.

Vault Hierarchy and Access Control

To understand how data is organized and protected, it helps to look at the hierarchy of the Vault and how access is granted.

  • Vault Server: The overarching server instance that stores encrypted blobs. The server itself cannot read any of the secrets.
  • Collections: A collection acts as an isolated namespace or folder for a group of related secrets. It is secured by a unique symmetric Collection Key.
  • Secrets: The actual key-value pairs stored within a collection. They are encrypted locally using the parent Collection’s Key before being sent to the server.
  • Clients: Identities (users or machines) that have generated their own local private/public keypair.
  • Roles: Access to a collection is granted by encrypting the Collection Key against a client’s public key. The server enforces authorization based on the client’s assigned role within that collection.

Access Roles

Clients are granted access to specific collections, not individual secrets. When a client is given access, they receive the Collection Key (securely wrapped), which allows them to decrypt all secrets within that collection. Their specific role dictates what actions they can perform via the Vault Server’s API:

  • Owner: Has full administrative rights over the collection. Can read and write secrets, invite new clients, change the roles of existing clients, and delete the collection entirely.
  • Member: Can read and write secrets within the collection. Useful for services that need to auto-generate and store new passwords, but cannot administer access for other machines.
  • Reader: Can only read secrets. Useful for read-only consumption in target machines where the secret was pre-seeded.

Pre-Provisioning Workflow

Step 1: Initialize the Collection

Set your orchestrator credentials and create a new collection.

export RESCILE_VAULT_CLIENTNAME="admin-orchestrator"
export RESCILE_VAULT_PASSWORD="my-super-strong-admin-password"

# Create a new collection
rescile-ce vault collection create "my-app-secrets"

Step 2: (Optional) Pre-Seed Secrets

Pre-seeding secrets is not mandatory. If a collection exists but a requested secret is not defined, the first client that attempts to access it will automatically trigger the creation of a secure random secret.

If you prefer to explicitly set known secrets:

# Set an external API token
rescile-ce vault secret put "my-app-secrets" "API_KEY" "sk-123456789"

# Auto-generate a strong password
rescile-ce vault secret put "my-app-secrets" "DB_PASSWORD"

Step 3: Grant Access via Invite Tokens

To grant a newly provisioned machine access to these secrets, create a time-bound invite token:

# Invite a client named "db-server-01" with a token valid for 1 hour
INVITE_TOKEN=$(rescile-ce vault collection invite "my-app-secrets" --client "db-server-01" --validity 1h)

echo "Copy this token to the target machine: $INVITE_TOKEN"

Step 4: Consuming Secrets on Target Machines

During the automated boot sequence, the target machine uses the invite token to securely claim access, generate its local keypair, and retrieve the shared secrets:

export RESCILE_VAULT_INVITE_TOKEN="<COPIED_INVITE_TOKEN>"
export RESCILE_VAULT_CLIENTNAME="db-server-01"

# Retrieve the pre-seeded secret
DB_PASS=$(rescile-ce vault secret get "my-app-secrets" "DB_PASSWORD")

echo "Applying DB_PASS to local database configuration..."

The invite token unwraps the shared collection key locally without exposing it to the server, ensuring zero-knowledge, end-to-end encrypted password sharing.

Web UI

While the CLI is ideal for automated workflows, human operators and external vendors often need a graphical interface to manage secrets securely.

Because Rescile Vault employs Zero-Knowledge End-to-End Encryption, the UI handles all cryptographic unwrapping and encryption directly inside the browser using WebCrypto.

Local UI

You can start a local instance of the Vault dashboard using the standalone client:

rescile-vault ui
# Output: Web UI started at http://127.0.0.1:54321

Server-Hosted UI

The Vault UI is also bundled into rescile-ce and rescile-portal. Access it via:

http://<host>:<port>/vault-ui/<collection_name>/<client_id>?secrets=API_TOKEN,DB_PASSWORD

Batch Operations

For bulk operations, the standalone rescile-vault client supports batch mode:

rescile-vault batch secrets.batch

Where secrets.batch contains:

collection create infra
secret put infra db_password
secret put infra api_token "sk-123456789"
collection invite infra --client db-server-01 --validity 7d

CLI Reference

Global Options:

  • --url <URL>: Vault base URL (env: RESCILE_VAULT_URL, default: http://localhost:7600)
  • --clientname <NAME>: Client identity (env: RESCILE_VAULT_CLIENTNAME)
  • --password <PASSWORD>: Master password (env: RESCILE_VAULT_PASSWORD)
  • --tpm: Use hardware TPM instead of a password

Secret Commands:

  • secret get <COLLECTION> <SECRET_NAME>: Retrieve a secret (auto-generates if missing)
  • secret put <COLLECTION> <SECRET_NAME> [VALUE]: Store a secret
  • secret delete <COLLECTION> <SECRET_NAME>: Delete a secret

Collection Commands:

  • collection create <NAME>: Create a new collection
  • collection invite <NAME> --client <CLIENT> [--validity <DURATION>]: Generate an invite token
  • collection delete <NAME>: Delete a collection
  • collection role <NAME> --client <CLIENT> --role <ROLE>: Update client role

Client Commands:

  • client delete [--client <CLIENT>]: Delete a client
  • client reset --client <CLIENT>: Reset a client’s credentials

See Vault Reference for complete documentation and examples.