# Config Vault (cfgvault)

[cfgvault](https://code.kevwe.com/cfgvault.git) is a minimalistic configuration vault for your application secrets.

## A Configuration Vault Service

Config Vault exposes a Rest interface to retrieve secrets from a KeePass keystore.

## Quick Start

### Minimal Configuration File

Create the following example configuration file:

```
$ cat $HOME/.config/cfgvault/config.json
{
  "endpoint":"127.0.0.1:8080",
  "keystore":"/path/to/keystore.kdbx",
  "secretkey":"/path/to/secretkey.keyx"
}
```

this is the minimal configuration file needed to test cfgvault locally over http or behind a reverse proxy.
The keystore and secretkey files must be created beforehand with KeePass or some compatible tool.

A proper configuration file for a production deployment should include TLS certificates and keys.

```
$ cat $HOME/.config/cfgvault/config.json
{
  "endpoint":"127.0.0.1:8433",
  "keystore":"/path/to/keystore.kdbx",
  "secretkey":"/path/to/secretkey.keyx",
  "server_tls_certificate":"/path/to/server.crt",
  "server_tls_key":"/path/to/server.key"
}
```

You can enable mutual TLS by providing a CA certificate to validate client certificates against, and switching mutual
authentication on:

```
$ cat $HOME/.config/cfgvault/config.json
{
  "endpoint":"127.0.0.1:8433",
  "keystore":"/path/to/keystore.kdbx",
  "secretkey":"/path/to/secretkey.keyx",
  "server_tls_certificate":"/path/to/server.crt",
  "server_tls_key":"/path/to/server.key",
  "server_ca":"/path/to/ca.crt",
  "validate_client_cert":true
}
```

The application allows you also to specify an array of IP subnets that are allowed to connect to the service:

```
$ cat $HOME/.config/cfgvault/config.json
{
  "endpoint":"127.0.0.1:8080",
  "keystore":"/path/to/keystore.kdbx",
  "secretkey":"/path/to/secretkey.keyx",
  "server_tls_certificate":"/path/to/server.crt",
  "server_tls_key":"/path/to/server.key",
  "allowlist":["127.0.0.1/8","10.2.3.4/24"],
  "server_ca":"/path/to/ca.crt",
  "validate_client_cert":true
}
```

All IP addresses not in the allowlist will be rejected with a 403 Forbidden response.

### Building cfgvault

```bash
cd cfgvault
cargo build --release
```

### Running cfgvault

You can just run the executable:

```bash
$ ./target/release/cfgvault
```

## Creating a Keystore file

cfgvault uses a KeePass keystore file to store your secrets.
You can create a new KeePass keystore file using the KeePass application or any compatible tool.
A lesser-known way to create a KeePass keystore file is to use the `keepassxc-cli` command-line tool.
Following we provide some examples on how to create/manage secrets in KeePass with the CLI.

### Create a Password Database

Make sure you have the `keepassxc-cli` command-line tool installed. You can create a new KeePass database with the
following command:

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
test -f ${KEYPASS_DB} && echo "db exists"
test -f ${KEYPASS_DB} && exit 1

keepassxc-cli db-create --set-key-file ${KEYPASS_FILE} ${KEYPASS_DB}
```

### Add an entry to your Passwords Database

You can do it like this:

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry_user=$1
entry=$2

keepassxc-cli add --key-file ${KEYPASS_FILE} --no-password ${KEYPASS_DB} -u ${entry_user} ${entry}  --password-prompt
```

or you can have your password manager to generate a password for you:

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry_user=$1
entry=$2

#keepassxc-cli add Passwords.kdbx -u larry -g wiki.gentoo.org

keepassxc-cli add --key-file ${KEYPASS_FILE} --no-password ${KEYPASS_DB} -u ${entry_user} --generate ${entry}
```

### List all of the entries in your password database

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx

keepassxc-cli ls --key-file ${KEYPASS_FILE}  --no-password ${KEYPASS_DB}
```

### Retrieve an entry

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry=$1

keepassxc-cli show -s --key-file ${KEYPASS_FILE}  --no-password ${KEYPASS_DB} ${entry} -a Password
```

### Delete an entry

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry=$1

keepassxc-cli rm --key-file ${KEEPASS_FILE} --no-password ${KEEPASS_DB} ${entry}
```

### Show a custom field from the selected entry

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry=$1

keepassxc-cli show -s --key-file ${KEYPASS_FILE}  --no-password ${KEYPASS_DB} ${entry} -a UserName
```

### Copy Secret to Clipboard

```
#! /bin/bash -x

KEYPASS_FILE=keepass.keyx
KEYPASS_DB=$HOME/.config/secure-passwords.kdbx
entry=$1

keepassxc-cli clip --key-file ${KEYPASS_FILE}  --no-password ${KEYPASS_DB} ${entry}
```

## License

[cfgvault](https://code.kevwe.com/cfgvault.git) is authored by [Paolo Lulli](https://lulli.net/about) 2026 and is
publicly available under the Affero GPL license.