Credential Management

DBConvert Streams separates configuration (connection names, hosts, ports) from secrets (passwords, certificates, keys). Configuration is stored in a config backend (SQLite for desktop, Consul for server). Secrets are encrypted in a dedicated secrets backend and merged at runtime.

Secrets backends

The backend is selected via the SECRETS_BACKEND environment variable:

Backend	Value	Use case
Encrypted file	`file` (default)	Desktop and single-server deployments
HashiCorp Vault	`vault`	Optional for server deployments

What is stored

Each connection stores a ConnectionSecrets record with the following fields:

Field	Description
`Password`	Database password
`DSN`	Generated connection string
`SSLMode`	SSL/TLS mode
`CACert`	CA certificate (PEM)
`ClientCert`	Client certificate (PEM)
`ClientKey`	Client private key (PEM)
`SSHPassword`	SSH tunnel password
`SSHPrivateKey`	SSH tunnel private key
`SSHPassphrase`	SSH key passphrase

Secrets never appear in config files, API responses to list endpoints omit SSH/SSL details, and credentials are only merged into connection objects at runtime when needed.

Encrypted file backend

The default backend encrypts all secrets into a single file using:

XChaCha20-Poly1305 for authenticated encryption
Argon2id for key derivation (3 iterations, 64 MB memory, 4 threads)

File format

Segment	Size	Description
Magic bytes	4 bytes	`DBCS`
Version	1 byte	Format version (currently `1`)
Salt	32 bytes	Random salt for Argon2id
Nonce	24 bytes	XChaCha20-Poly1305 nonce
Ciphertext	Variable	Encrypted JSON with auth tag

Master key

The master key is used with Argon2id to derive the encryption key. It is resolved in this order:

SECRETS_MASTER_KEY environment variable (if set)
OS keyring (service: DBConvert Streams, user: secrets-master-key)
Auto-generated (32 random bytes, base64-encoded) and stored in the OS keyring

On desktop, the master key is managed automatically via the OS keyring. For headless or server deployments using the file backend, set SECRETS_MASTER_KEY explicitly.

File location

Set with the SECRETS_FILE_PATH environment variable — the location is always explicit, there is no implicit default. The desktop app points it at its own data directory (for example ~/.local/share/dbconvert-streams/secrets/secrets.enc on Linux).

Vault backend (optional)

Server deployments can optionally store secrets in HashiCorp Vault using the KV v2 secrets engine. If not configured, the encrypted file backend is used by default.

Secrets are stored at: secret/data/connections/{userID}/{connectionID}

The backend automatically enables the KV v2 engine if not already present, and includes retry logic for initial connection (10 attempts, 3-second intervals).

Configuration

Environment variable	Description	Default
`VAULT_ADDR`	Vault server address	`http://localhost:8200`
`VAULT_TOKEN`	Vault authentication token	(required)

Environment variables reference

Variable	Description	Default
`SECRETS_BACKEND`	Backend selection: `file` or `vault`	`file`
`SECRETS_FILE_PATH`	Path to the encrypted secrets file	(required, no default)
`SECRETS_MASTER_KEY`	Master key for file backend encryption	Auto-generated, stored in OS keyring
`VAULT_ADDR`	Vault server address	`http://localhost:8200`
`VAULT_TOKEN`	Vault authentication token	(required for vault backend)

SSL Configuration — SSL/TLS connection setup
Database Access Configuration — Network and firewall setup
Connections API Workflows — Connection management