# How Chat2DB Implements Credential Storage Security with AES-GCM Encryption

> Chat2DB secures your credentials with robust AES-GCM encryption. Learn how it protects your database passwords and AI API keys at rest against workspace compromises.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: security
- Published: 2026-07-28

---

**Chat2DB encrypts all persisted database passwords and AI API keys using AES-GCM with a 256-bit key before writing them to disk, ensuring credentials remain protected at rest even if workspace files are compromised.**

Chat2DB, the open-source database management tool from OtterMind, handles sensitive credentials including database passwords and AI model API keys. Understanding how this application secures credential storage is critical for developers evaluating its enterprise readiness. The source code reveals a multi-layered approach combining strong cryptography with secure key management practices that prevent plaintext exposure of secrets in local storage files.

## Core Encryption Architecture

The security model centers on a single utility class that handles all cryptographic operations for the application.

### AES-GCM Implementation in `AesGcmUtil`

Located at [`chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/AesGcmUtil.java) (lines 55-104), the `AesGcmUtil` class implements **AES-GCM/NoPadding** encryption via `TRANSFORMATION = "AES/GCM/NoPadding"`. This mode provides authenticated encryption, simultaneously ensuring confidentiality and integrity of stored secrets through built-in integrity checking.

Key technical specifications from the source code include:

- **256-bit key strength**: Uses `KEY_LENGTH_BYTES = 32` (32 bytes equals 256 bits)
- **Domain-separated AAD**: Two distinct associated-data strings prevent cross-context attacks:
  - `DATASOURCE_PASSWORD_AAD` for database credentials
  - `AI_MODEL_API_KEY_AAD` for AI service keys
- **Public API methods**: `encrypt()`, `decrypt()`, `encryptAiModelApiKey()`, and `decryptAiModelApiKey()` expose the functionality (lines 55-68)

The actual cryptographic implementation (lines 71-88 and 90-104) handles initialization vector (IV) generation, GCM authentication tag computation, and verification, providing protection against tampering and unauthorized decryption.

### Secure Key Management via `CommunityEncryptionKeyStore`

The encryption key itself is managed by `CommunityEncryptionKeyStore` ([`chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/CommunityEncryptionKeyStore.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/security/CommunityEncryptionKeyStore.java), lines 40-115). This component implements defense-in-depth for key material through multiple provisioning strategies and filesystem hardening.

**Key provisioning hierarchy** (checked in order of priority):
1. JVM system property: `chat2db.community.encryption-key`
2. Environment variable: `CHAT2DB_COMMUNITY_ENCRYPTION_KEY`
3. Dedicated key file: `~/.config/chat2db-community/encryption.key`

**Secure generation and storage**:
When running in Community-Desktop mode without an existing key, the system generates a cryptographically random 32-byte key using `SecureRandom`. The key file is created with **owner-only POSIX permissions** (`rw-------` for files, `rwx------` for directories). On non-POSIX systems, the code falls back to Java's `setReadable(false)` and `setWritable(false)` methods to restrict access.

After key usage, the raw key bytes are cleared from memory using `Arrays.fill()` to minimize exposure in heap dumps or memory analysis.

## Where Encryption Protects Credentials

Chat2DB applies these cryptographic protections at specific integration points where secrets enter long-term storage.

### Database Passwords in Workspace Storage

When persisting data source definitions, `LocalWorkspaceStorage` ([`chat2db-community-storage/src/main/java/ai/chat2db/community/storage/LocalWorkspaceStorage.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-storage/src/main/java/ai/chat2db/community/storage/LocalWorkspaceStorage.java)) encrypts password fields before writing to JSON workspace files. The relevant encryption calls occur at lines 65, 83, and 240-244, using `AesGcmUtil.configured().encrypt(password)` to transform plaintext into ciphertext using the datasource-specific AAD.

### AI Model API Keys

AI configuration receives identical protection through the specialized AAD variant. In `AiModelConfigServiceImpl` ([`chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/ai/AiModelConfigServiceImpl.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-domain/chat2db-community-domain-core/src/main/java/ai/chat2db/community/domain/core/impl/ai/AiModelConfigServiceImpl.java), lines 399-407), API keys are encrypted via `encryptAiModelApiKey()` before storage, ensuring cryptographically separated protection from database credentials even if both are stored in the same workspace file.

## Security Controls and Hardening Measures

The credential storage implementation in Chat2DB includes several defense-in-depth mechanisms:

- **Strong cryptography**: AES-GCM with 256-bit keys and unique initialization vectors for every encryption operation
- **Authenticated encryption**: GCM mode provides integrity checking alongside confidentiality, detecting any tampering with stored values
- **Cryptographic separation**: Distinct AAD values prevent ciphertext substitution attacks between database passwords and AI keys
- **Flexible key provisioning**: Support for external key injection via environment variables or JVM properties enables enterprise key management integration
- **Filesystem hardening**: Owner-only permissions on key files prevent unauthorized local access by other users or processes
- **Memory safety**: Explicit clearing of key material after cryptographic operations via `Arrays.fill()`
- **Thread safety**: `AesGcmUtil.configured()` provides a singleton instance ensuring consistent, synchronized key usage across the application

## Summary

- Chat2DB uses **AES-GCM/NoPadding** with 256-bit keys to encrypt all credentials before persisting them to workspace storage
- Database passwords and AI API keys use **domain-separated associated data (AAD)** to prevent cross-context cryptographic attacks
- Encryption keys can be provisioned via **environment variables, system properties, or secure file storage** with owner-only POSIX permissions
- The `AesGcmUtil` and `CommunityEncryptionKeyStore` classes in the `chat2db-community-tools` module centralize all cryptographic operations
- **Memory clearing** (`Arrays.fill`) and secure random generation minimize exposure of sensitive material in memory

## Frequently Asked Questions

### What encryption algorithm does Chat2DB use for credential storage?

Chat2DB uses **AES-GCM (Advanced Encryption Standard in Galois/Counter Mode)** with NoPadding, implemented in [`AesGcmUtil.java`](https://github.com/OtterMind/Chat2DB/blob/main/AesGcmUtil.java). This provides authenticated encryption using 256-bit keys, ensuring both confidentiality and integrity of stored credentials according to modern cryptographic standards.

### Where is the encryption key stored in Chat2DB?

The encryption key is resolved through a cascading priority: first checking the `chat2db.community.encryption-key` system property, then the `CHAT2DB_COMMUNITY_ENCRYPTION_KEY` environment variable, and finally falling back to `~/.config/chat2db-community/encryption.key`. When auto-generated, the key file receives restrictive owner-only POSIX permissions (`rw-------`).

### How does Chat2DB protect against memory dumps exposing credentials?

The `CommunityEncryptionKeyStore` explicitly clears encryption key bytes from memory using `Arrays.fill()` after cryptographic operations complete. While this reduces exposure window, credentials may still exist in memory briefly during active use, which is standard for applications that must actively decrypt data.

### Can I use my own encryption key with Chat2DB?

Yes. You can supply your own 256-bit key via the `CHAT2DB_COMMUNITY_ENCRYPTION_KEY` environment variable or the `chat2db.community.encryption-key` JVM property. Alternatively, specify a custom key file path using `chat2db.community.encryption-key-file` or its environment variable equivalent `CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE`.