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

> Learn how to export and encrypt DBX connection configurations using AES-GCM. Securely transfer your DBX settings between machines with a passphrase. A complete guide.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/stores/connectionStore.ts) (lines 4674-4682), the export logic checks for passphrase presence before invoking encryption:

```typescript
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:

```typescript
{
  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`](https://github.com/t8y2/dbx/blob/main/configCrypto.ts) validates the envelope structure before processing.

The import workflow (approximately lines 4850-4857 in [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/connectionStore.ts)) handles decryption as follows:

```typescript
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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/configCrypto.ts) module exposes functions for programmatic use. The **exportConfigs()** helper in [`apps/desktop/src/composables/useSchemaDiffConfig.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/composables/useSchemaDiffConfig.ts) provides additional packaging utilities for configuration data.

### Encrypting a Configuration

```typescript
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

```typescript
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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/apps/desktop/src/i18n/locales/en.ts)** – Localization strings including `passphraseExportHint` and `passphraseImportHint` (lines 1188-1190).
- **[`apps/desktop/src/composables/useSchemaDiffConfig.ts`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/configCrypto.ts) for cryptographic operations and [`connectionStore.ts`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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.