How to Export and Encrypt DBX Connection Configurations: A Complete Guide

DBX stores connection definitions in JSON format that can be exported as plain text or encrypted using AES-GCM with a PBKDF2-derived key, allowing secure transfer between machines using a user-provided passphrase.

DBX is an open-source database management tool that provides enterprise-grade security for connection configuration exports. The encryption system implemented in the t8y2/dbx repository uses the Web Crypto API to protect sensitive database credentials when migrating settings between workstations.

The Encryption Architecture

DBX employs AES-GCM (Galois/Counter Mode) encryption with keys derived via PBKDF2 (Password-Based Key Derivation Function 2). According to the source code in apps/desktop/src/lib/backend/configCrypto.ts, the implementation uses 100,000 iterations of SHA-256 hashing to stretch user passphrases into 256-bit encryption keys.

Each encrypted export generates:

• A 16-byte random salt for key derivation uniqueness
• A 12-byte random IV (Initialization Vector) for AES-GCM operations
• Base64-encoded ciphertext containing the configuration payload

How to Export Encrypted Configurations

When you initiate an export through the DBX desktop application, the connectionStore orchestrates the following workflow:

1. Serialize the configuration – The store gathers all connection objects and converts them to a JSON string.
2. Optional passphrase collection – The UI displays a passphrase field (defined by passphraseExportHint in apps/desktop/src/i18n/locales/en.ts) for optional encryption.
3. Conditional encryption – If a passphrase is provided, the store calls encryptConfig() from configCrypto.ts.
4. File generation – The system writes either plain JSON or an encrypted envelope to a .dbx file.

Export Flow Implementation

In apps/desktop/src/stores/connectionStore.ts (lines 4674-4682), the export logic checks for passphrase presence before invoking encryption:

async function exportConfig(passphrase?: string) {
  const json = JSON.stringify({ connections: this.connections });
  if (passphrase) {
    const encrypted = await encryptConfig(json, passphrase);
    await saveFile(JSON.stringify(encrypted, null, 2));
  } else {
    await saveFile(json);
  }
}

The encryptConfig() function returns an object with the structure:

{
  format: "dbx-encrypted",
  version: 1,
  salt: "...",   // base64 encoded
  iv: "...",     // base64 encoded
  data: "..."    // base64 ciphertext
}

Importing and Decrypting Configurations

During import, DBX automatically detects encrypted files by checking for the format: "dbx-encrypted" property. The isEncryptedConfig() utility in configCrypto.ts validates the envelope structure before processing.

The import workflow (approximately lines 4850-4857 in connectionStore.ts) handles decryption as follows:

async function importConfig(fileContent: string) {
  const parsed = JSON.parse(fileContent);
  const payload = isEncryptedConfig(parsed)
    ? await decryptConfig(parsed, await askPassphrase())
    : fileContent;
  const config = JSON.parse(payload);
  this.loadConnections(config.connections);
}

When the system detects an encrypted payload, it prompts the user with the passphraseImportHint string (defined at lines 1188-1190 in apps/desktop/src/i18n/locales/en.ts) and passes the input to decryptConfig(), which reverses the PBKDF2 key derivation and AES-GCM decryption process.

Working with the Encryption API

While DBX handles encryption automatically through the UI, the underlying configCrypto.ts module exposes functions for programmatic use. The exportConfigs() helper in apps/desktop/src/composables/useSchemaDiffConfig.ts provides additional packaging utilities for configuration data.

Encrypting a Configuration

import { encryptConfig } from "@/lib/backend/configCrypto.ts";

const json = JSON.stringify({ connections: [...] });
const passphrase = "my-secure-phrase";

const encrypted = await encryptConfig(json, passphrase);

Decrypting a Configuration

import { decryptConfig } from "@/lib/backend/configCrypto.ts";

const payload = /* read from .dbx file */;
const passphrase = "my-secure-phrase";

const plainJson = await decryptConfig(payload, passphrase);
// Returns: '{"connections":[...]}'

Key Implementation Files

Understanding the following source files is essential for customizing or debugging the export functionality:

• apps/desktop/src/lib/backend/configCrypto.ts – Core encryption utilities containing encryptConfig, decryptConfig, and isEncryptedConfig functions, plus the PBKDF2_ITERATIONS constant.
• apps/desktop/src/stores/connectionStore.ts – State management that triggers exports (lines 4674-4682) and handles imports (lines ~4850-4857).
• apps/desktop/src/i18n/locales/en.ts – Localization strings including passphraseExportHint and passphraseImportHint (lines 1188-1190).
• apps/desktop/src/composables/useSchemaDiffConfig.ts – Provides the exportConfigs() helper for packaging configuration data.

Summary

• DBX exports use JSON format with optional AES-GCM encryption via the Web Crypto API.
• Encryption requires a user-provided passphrase processed through PBKDF2 with 100,000 SHA-256 iterations.
• Encrypted files contain base64-encoded salt, IV, and ciphertext with the format identifier "dbx-encrypted".
• Source locations include configCrypto.ts for cryptographic operations and connectionStore.ts for UI workflow orchestration.
• Import detection automatically recognizes encrypted files and prompts for decryption passphrases.

Frequently Asked Questions

What encryption algorithm does DBX use for configuration exports?

DBX uses AES-GCM (Galois/Counter Mode) with 256-bit keys derived via PBKDF2. The implementation generates a random 16-byte salt and 12-byte IV for each export operation, using 100,000 iterations of SHA-256 hashing to derive the encryption key from your passphrase.

Can I export DBX configurations without encryption?

Yes. The passphrase field in the export dialog is optional. If you proceed without entering a passphrase, the connectionStore writes the raw JSON configuration directly to the .dbx file without invoking encryptConfig(). This creates a human-readable file containing your connection definitions in plaintext.

How does DBX detect that an imported file is encrypted?

The system calls isEncryptedConfig() from configCrypto.ts to check for the presence of format: "dbx-encrypted" in the parsed JSON object. If this property exists, the import flow in connectionStore.ts automatically prompts for the passphrase and routes the data through decryptConfig() before loading the connections.

Where are the encryption constants defined in the DBX source code?

The PBKDF2 iteration count and other cryptographic parameters are defined in apps/desktop/src/lib/backend/configCrypto.ts. This file exports the encryptConfig and decryptConfig functions used by the desktop application's connection store, along with the PBKDF2_ITERATIONS constant set to 100,000.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}