Credential storage (no plaintext passwords)

Save the password or token in the OS-native secret store so it does not appear in odbc.ini, the registry, or scripts.

Syntax

(use the DSN setup GUI's Save password flow)

Description

## Why An ODBC DSN is conventionally a plain INI file (Linux, macOS) or registry entry (Windows). Hand-editing `Pwd=...` puts the password on disk in cleartext, exposed to anything that can read the user's home directory or registry hive. The Delta Forge driver looks the password up from the OS secret store first when the connection string omits `Pwd=`, so you can leave the secret out of the DSN entirely. ## Per-platform backends | Platform | Backend | |---|---| | Windows | DPAPI per-user encryption + a registry entry under `HKCU\Software\DeltaForge\Credstore` | | macOS | Keychain Services (login keychain, generic password class) | | Linux | libsecret over D-Bus (GNOME Keyring, KWallet, KeePassXC, any Secret-Service implementation) | | Linux fallback | mode-0600 file under `~/.config/deltaforge/credstore/`, used when no Secret Service is running | The Linux fallback exists for headless servers (CI runners, containers) that have no D-Bus session. It is not encrypted at rest; rely on POSIX file permissions. ## Lookup order at connect time 1. If `Token=` is present in the connection string, use it directly. 2. If `Pwd=` is present in the connection string, use it directly. 3. Otherwise, look up `Pwd:<Uid>` in the OS secret store under the DSN name. If found, use it. 4. As a secondary fallback, look up `Token:<Uid>`. If found, treat it as a bearer token. 5. If nothing is found, the connection fails with an authentication error noting that no credential was supplied. An explicit `Pwd=` always wins. To force the keychain lookup, omit `Pwd=` from both the connection string and the DSN file. ## Saving credentials The DSN setup GUI on each platform writes to the OS keychain when the user fills in a password and saves the DSN: - **Windows**: the **DeltaForge ODBC Driver Setup** dialog launched from the ODBC Data Source Administrator's **Add** flow. - **macOS**: the macOS DSN configurator that ships with the driver bundle. - **Linux**: the Linux DSN configurator that ships with the driver package. Each UI saves `Pwd:<Uid>` (and `Token:<Uid>` when bearer auth is selected) under the DSN name. The next connection that omits `Pwd=` reads the stored value.

Examples

# After saving via the DSN setup GUI, connect without a Pwd= key
isql -v DeltaForge

# Driver-string form: omit Pwd= to trigger the keychain lookup
Driver={DeltaForge ODBC Driver};Server=https://df.example.com;Uid=alice@example.com

Pitfalls

• On a headless Linux host, the libsecret backend has no D-Bus session to bind to and the driver falls back to the mode-0600 file under `~/.config/deltaforge/credstore/`. The fallback is not encrypted at rest; protect the directory with POSIX permissions.
• macOS Keychain prompts for permission the first time a process reads an entry. If the prompt is dismissed or the BI tool runs from launchd, subsequent reads silently fail. Approve the prompt in **Keychain Access** by setting **Always Allow** for the requesting application.
• If both `Pwd:<Uid>` and `Token:<Uid>` exist for the same Uid under the same DSN, the password lookup wins because it is checked first.

See Also

• ODBC_CONN_PWD
• ODBC_CONN_TOKEN
• ODBC_CONN_AUTHMODE