Reference

Rescile Vault

How to run the built-in Vault server and use the rescile-ce vault client for Zero-Knowledge secret management and pre-provisioning.

Edit this page on GitHub

Using the Rescile Vault

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.

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

2. Using the Vault Client

You can interact with the running vault server using the built-in client wrapper: rescile-ce vault.

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

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

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

Visualizing the Hierarchy

graph TD
    subgraph Vault Server
        subgraph CollectionA [Collection: my-app-secrets]
            Sec1[Secret: API_KEY]
            Sec2[Secret: DB_PASSWORD]
        end
        subgraph CollectionB [Collection: monitoring-secrets]
            Sec3[Secret: DATADOG_TOKEN]
        end
    end

    ClientAdmin([admin-orchestrator]) -->|Owner| CollectionA
    ClientAdmin -->|Owner| CollectionB

    ClientDB([db-server-01]) -->|Member| CollectionA
    ClientMon([monitoring-node]) -->|Reader| CollectionA
    ClientMon -->|Reader| CollectionB

How Roles are Involved: 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.

4. Pre-Configuring Collections (Orchestrator Workflow)

A common use case is for an orchestrator (like a CI/CD pipeline or a dedicated admin machine) to define a collection and determine which clients can access it.

Note: Secret pre-population is not mandatory. The main purpose of the orchestrator is to define the collections and securely issue invite tokens establishing the trust boundary.

Step A: Initialize the Collection

Set your orchestrator credentials and create a new collection.

(Note: If you are using the enterprise version of rescile-vault, it includes native TPM and HSM support. Your keys are bound to the hardware enclave, so there is no need to define a RESCILE_VAULT_PASSWORD.)

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

rescile-ce vault collection create "my-app-secrets"

Step B: (Optional) Put Secrets into the Vault

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. This secret is immediately encrypted and saved to the vault, so any subsequent access will automatically use and show this exact same secret.

If you still prefer to explicitly set a known secret (or manually trigger auto-generation), you can do so:

# Explicitly set a known secret (e.g., an external API token) in the my-app-secrets coallection
rescile-ce vault secret put "my-app-secrets" "API_KEY" "sk-123456789"

# Auto-generate a strong password (e.g., a database password) - password is omitted
rescile-ce vault secret put "my-app-secrets" "DB_PASSWORD"

Step C: Use the Provisioning API to Generate Invite Tokens

To grant a newly provisioned machine (which does not yet have a password or keypair) access to these secrets, you use the Provisioning API to 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"

5. Consuming Pre-Provisioned Secrets (Target Machine)

During the automated boot sequence (e.g., via cloud-init or a provisioning script), the target machine uses the provided invite token to securely claim access, generate its local keypair, and retrieve the shared passwords.

There are two ways of accepting an invite token on the target machine:

  1. Environment Variable: Define the invite token as an environment variable (RESCILE_VAULT_INVITE_TOKEN), typically injected securely by your provisioning tool.
  2. HTTP GET: Access the invite token dynamically using curl or any other HTTP GET request. The client automatically attempts to fetch the token via the API if the environment variable is missing, but you can also retrieve it manually.

Example of fetching the invite token with curl:

curl -s http://localhost:7600/vault/v1/invite/db-server-01

Because the target machine needs a local password to encrypt its own private key, we can generate a random ephemeral password on the fly. However, if no RESCILE_VAULT_PASSWORD environment variable is provided, the vault client will automatically generate a strong password and store it securely on the filesystem (/etc/rescile/vault.password for root, or ~/.config/rescile/vault.password for standard users).

Note: When using the Rescile Enterprise edition, the machine’s local TPM (Trusted Platform Module) can be utilized to hardware-bind the secret, completely eliminating the need for filesystem-based password storage or manual password injection.

# Method 1: Environment injected by the orchestrator / provisioning tool
export RESCILE_VAULT_INVITE_TOKEN="<COPIED_INVITE_TOKEN>"
export RESCILE_VAULT_CLIENTNAME="db-server-01"

# Method 2: Fetching dynamically 
# (If RESCILE_VAULT_INVITE_TOKEN is omitted, the client fetches it automatically)
# export RESCILE_VAULT_CLIENTNAME="db-server-01"

# 2. (Optional) Generate an ephemeral local password (or let the client auto-generate and store it)
# export RESCILE_VAULT_PASSWORD=$(openssl rand -base64 32)

# 3. Claim the invite and retrieve the shared pre-seeded secret
DB_PASS=$(rescile-ce vault secret get "my-app-secrets" "DB_PASSWORD")

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

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

6. Administering Roles

As explained in the hierarchy, access to collections is governed by roles. By default, the client that creates a collection is assigned the Owner role. When invited clients successfully claim an invite token, they are assigned the Member role.

To change a client’s role (for example, to restrict a machine to Reader), an Owner can use the collection role command:

# Promote a client to Owner
rescile-ce vault collection role "my-app-secrets" --client "db-server-01" --role "Owner"

# Demote a client to Reader
rescile-ce vault collection role "my-app-secrets" --client "db-server-01" --role "Reader"

Owners can also manage access by revoking pending invites or completely removing a client’s access to the collection:

# Revoke a pending invite before it is claimed
rescile-ce vault collection revoke "my-app-secrets" --client "db-server-02"

# Remove an existing client from the collection
rescile-ce vault collection remove-client "my-app-secrets" --client "db-server-01"

Graph-Driven Provisioning Example

By leveraging Rescile’s graph generation, you can fully automate the generation of both the orchestrator script and the client consumption scripts using TOML output models:

# output/provision_vault.toml
origin_resource = "vault"

[[output]]
resource_type = "provision_script"
name = "seed-vault-{{ origin_resource.name }}"
filename = "seed-{{ origin_resource.name }}.sh"
template = '''
#!/usr/bin/env bash
export RESCILE_VAULT_CLIENTNAME="admin-orchestrator"
export RESCILE_VAULT_PASSWORD="${ADMIN_VAULT_PASSWORD}"

rescile-ce vault collection create "{{ origin_resource.name }}"
rescile-ce vault secret put "{{ origin_resource.name }}" "SHARED_PASSWORD"

{% for client in origin_resource.ACCESSED_BY | default(value=[]) %}
TOKEN=$(rescile-ce vault collection invite "{{ origin_resource.name }}" --client "{{ client.name }}" --validity 1h)
echo "export RESCILE_VAULT_INVITE_TOKEN=$TOKEN" > /tmp/invite_{{ client.name }}.env
{% endfor %}
'''