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.

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.

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

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)

Note: While Rescile’s Graph Synchronizer fully automates this entire process based on your TOML models (see Secrets Architecture), you can also perform these steps manually using the CLI.

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"

# my-app-secrets is the collection name
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: Grant access to client (Generate Invite Tokens if client is not yet known)

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 three 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. Automatic fetching: If no RESCILE_VAULT_INVITE_TOKEN is set and no RESCILE_VAULT_PASSWORD or password file exists. The vault client tries to discover the invite token.
  3. 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"

7. Web UI

While the CLI is ideal for automated machine-to-machine (M2M) workflows, human operators and external vendors often need a graphical interface to manage their secrets securely without installing CLI tools.

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

There are two ways to access the Web UI:

1. Local UI (via the CLI)

You can start a local instance of the Vault dashboard using the standalone client. This spins up a lightweight web server on a random local port, allowing you to manage your collections and secrets visually using your local identity and master key:

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

2. Server-Hosted UI (For External Vendors)

The Vault UI is also bundled natively into the central rescile-ce and rescile-portal components. This is ideal for external vendors who need to securely input API tokens without installing any tools.

The server-hosted Vault UI is accessible via a web browser. The URL is composed of the collection name, the client’s identity, and optionally a comma-separated list of required secret names:

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

When an external user navigates to this URL:

  1. They will be prompted to create or enter their master password.
  2. The UI will automatically claim any pending invite tokens for the client_id via the API.
  3. The local browser generates the necessary keypair, derives the session keys, and unwraps the collection key locally.
  4. The user is presented with a simple interface to input or update the requested secrets (API_TOKEN, DB_PASSWORD), which are encrypted directly in the browser before being sent back to the server.

Graph-Driven Provisioning Example

By leveraging Rescile’s graph environment and graph-native secrets architecture (see Secrets Architecture), you can fully automate the generation of both the orchestrator seed script and the per-client consumption scripts. The graph acts as the Control Plane: vault resources define the secret boundary, collections emerge from groups of clients sharing the same secret, and pre-provisioned client resources are the consumers.

The example can be found on GitHub: https://github.com/rescile/vault_example

Appendix: End-to-End Walkthrough

The following walkthrough demonstrates a complete Zero-Knowledge provisioning flow — from an orchestrator creating a collection and issuing invite tokens, to clients enrolling and retrieving a shared secret, to an unauthorized client being correctly denied access.

1. Orchestrator Creates the Collection

The orchestrator authenticates and creates a new collection named collectionname. This client is automatically assigned the Owner role.

# Create the collection
rescile-ce vault --password test1 --clientname orchestrator collection create collectionname

2. Orchestrator Invites client1

The orchestrator generates a time-bound invite token granting client1 access to collectionname. The token is printed to stdout and must be securely delivered to the target machine.

rescile-ce vault --password test1 --clientname orchestrator collection invite collectionname --client client1
PS57eJ5lVSX0w5GSbpNlAEioNR8jDSqBUz189uZ2iSM

The invite token for client1 is returned. Deliver this securely to the target machine.

3. client1 Enrolls and Retrieves the Secret

client1 claims the invite token via autodiscovery and requests secretname from collectionname. Because the secret does not yet exist, the vault automatically generates a strong random value, stores it encrypted, and returns it. All subsequent requests for this secret — by any enrolled client — will return this same value.

rescile-ce vault --password test2 --clientname client1 secret get collectionname secretname
IulhFxfj$wvwp9liOTyCbfzVhsMm1g83

The auto-generated secret value for secretname in collectionname is returned and persisted in the vault.

4. Orchestrator Invites client2

The orchestrator issues a second invite token, this time for client2. Each client receives its own unique token.

rescile-ce vault --password test1 --clientname orchestrator collection invite collectionname --client client2
JTr1XHRLae5CNBqqwTt-VrfcJkzSJaY8lU-vHmpTVzo

The invite token for client2 is returned.

5. client2 Enrolls and Retrieves the Same Secret

client2 enrolls using its own credentials and invite token. Despite using a completely different password, it retrieves the exact same secret value as client1. This is the core of the Zero-Knowledge model — the shared Collection Key is wrapped independently for each client, so no two clients share credentials, yet all see a consistent secret.

rescile-ce vault --password test7 --clientname client2 secret get collectionname secretname
IulhFxfj$wvwp9liOTyCbfzVhsMm1g83

client2 receives the same secret value, decrypted entirely on the client side.

6. client3 Is Denied Access

client3 has never been issued an invite token and has not enrolled in collectionname. Any attempt to access the collection is rejected by the server.

rescile-ce vault --password test7 --clientname client3 secret get collectionname secretname
Vault command failed: Collection 'collectionname' not found

Access is denied. client3 has no knowledge of the collection or its contents — the server returns no information that could aid enumeration.

8. Managing Clients (Delete and Reset)

Over time, you may need to offboard machines or recover access for clients that have lost their master password. The Vault provides two commands for client lifecycle management:

Deleting a Client

To completely remove a client’s identity from the Vault (for example, when decommissioning a server), use the delete command. This can be executed by the client itself, or by a collection Owner:

rescile-ce vault client delete [--client <CLIENT>]

This command securely removes the client’s public key, enrolled access, and any pending invitations. If the client was the sole owner and member of any collections, those collections (and their secrets) will be automatically pruned.

Resetting a Client

If a client loses its master password or its TPM hardware is replaced, it will no longer be able to decrypt its private key. A vault orchestrator (or a collection Owner) can issue a reset token to allow the client to re-enroll without needing to manually remove and recreate the client profile.

RESET_TOKEN=$(rescile-ce vault client reset --client "db-server-01")
echo "Deliver this token securely: $RESET_TOKEN"

When the client uses this token (via RESCILE_VAULT_INVITE_TOKEN), its previous keys will be wiped, and it will generate a new cryptographic identity. Note: Resetting a client automatically removes it from all previously joined collections because its old public key (used to wrap the collection keys) is no longer valid. The client will need to be re-invited to any required collections after the reset.

9. Batch Mode

For bulk operations (like bootstrapping a new environment), the standalone rescile-vault client supports a batch mode that reads commands sequentially from a file. This is much faster than running the CLI multiple times because it authenticates and fetches the required state only once.

secrets.batch

# Create the infrastructure collection
collection create infra

# Pre-seed secrets
secret put infra db_password
secret put infra api_token "sk-123456789"

# Issue invites
collection invite infra --client db-server-01 --validity 7d

Execute the batch script:

rescile-vault batch secrets.batch

10. 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, default: $USER@$HOSTNAME)
  • --password <PASSWORD>: Master password (env: RESCILE_VAULT_PASSWORD)
  • --tpm: Use hardware TPM instead of a password (requires tpm feature, env: RESCILE_VAULT_TPM)

Secret Commands:

  • secret get <COLLECTION> <SECRET_NAME>: Retrieve a secret. Generates and stores one if it doesn’t exist.
  • secret put <COLLECTION> <SECRET_NAME> [VALUE]: Store a specific value, or auto-generate one if omitted.
  • secret delete <COLLECTION> <SECRET_NAME>: Delete a secret from a collection.

Collection Commands:

  • collection create <NAME>: Create a new collection and become its Owner.
  • collection invite <NAME> --client <CLIENT> [--validity <DURATION>] [--role <ROLE>]: Generate an invite token for another client.
  • collection delete <NAME>: Delete an entire collection.
  • collection remove-client <NAME> --client <CLIENT>: Remove a client’s access to the collection.
  • collection role <NAME> --client <CLIENT> --role <ROLE>: Update a client’s role (Owner, Member, Reader).
  • collection revoke <NAME> --client <CLIENT>: Revoke a pending, unclaimed invite.

Client Commands:

  • client delete [--client <CLIENT>]: Delete the currently authenticated client, or a specific client if you are a collection Owner, from the server entirely.
  • client reset --client <CLIENT>: Generate a reset token for a client that lost their master key, allowing them to re-enroll.

Other Commands:

  • batch <FILE>: Execute multiple CLI commands sequentially from a text file.
  • ui: Start the embedded React Web UI locally.