Security

What BroadSQL protects, how, and what stays your responsibility.

The Connections Definition File (CDF)

Every connection you define (JDBC URL, user name, password), every Database Group, Environment and API definition lives in the CDF, an H2 database file encrypted with H2's file encryption (CIPHER=AES). With the bundled H2 2.3.232, the file is encrypted with AES-128. The key is derived from the master password with PBKDF2-HMAC-SHA256, an 8-byte random salt and 10 iterations.

The master password opens the whole file. BroadSQL uses it both as the file password and as the password of the database's administrator account, so there is only one password to remember. Inside the opened CDF, the passwords of your connections are ordinary column values: anyone who knows the master password can read them. BroadSQL does not add a second encryption layer on top of the CDF's own encryption.

Your master password

The master password is what protects a copy of the CDF: a backup, a file left on a shared folder, a lost laptop. Nothing in BroadSQL exposes the CDF over the network; someone needs a copy of the file to try to open it.

Someone who has a copy can only guess the master password, try after try. Each try needs the key derivation described above. On an ordinary 16-core PC, H2's key derivation runs about 400,000 times per second on one core and a few million times per second on all cores (measured with the bundled H2). This is a benchmark of one step, not a complete attack: it shows why the length of the master password matters, not how long a real attack would take. Specialized hardware is faster; we did not measure it.

In practice:

• 8 random lowercase letters (about 2 x 10^11 possibilities) can be tried in about a day on one PC.
• 12 random letters and digits (about 3 x 10^21 possibilities) are far beyond any practical time, even thousands of times faster.
• A dictionary word, a name or a short password falls quickly whatever its characters.

Recommendation: a long passphrase without spaces (for example four or five unrelated words joined by symbols), or 12 or more random characters.

Accepted characters

A master password has 2 to 256 characters: letters, digits and symbols of the ISO-8859-1 (Latin-1) character set, such as a-z A-Z 0-9 é ü ß $ # @ ! % & * - _ +. Quotes, semicolons and backslashes are accepted.

SET MASTER PASSWORD refuses, before changing anything:

• spaces (and other blank characters): the database engine separates its two passwords at the first space;
• characters outside Latin-1, such as € or Chinese characters: with them, the engine encrypts the file with a key it cannot derive again when the file is opened, so the CDF would no longer open with any password;
• control characters (tab, line breaks) and invisible characters.

Every accepted character was checked with the bundled H2: a CDF encrypted with it opens again with all its data. If your console cannot type an accented letter reliably, keep to ASCII letters, digits and symbols: you must be able to type the same characters at every login.

The default master password

Every new installation ships with the same master password, clipper8AD, documented publicly, this page included. It protects nothing. Change it with SET MASTER PASSWORD; before adding real connections.

Changing the master password safely

SET MASTER PASSWORD never encrypts the CDF again in place. It first saves a backup in the backups folder next to the CDF, encrypts a copy with the new password, checks that the copy opens with it and holds exactly the same data, then puts the copy in place of the CDF and checks it once more. If any step fails, the CDF is left as it was and the message says so. If BroadSQL is stopped during the change, the next login completes it (with the new password) or offers to undo it (with the previous one). See CDF maintenance.

The backup (<CDF name>_masterpwd_<date>_<time>.zip) is encrypted with the previous master password. Keep it as safely as the CDF, or delete it when you no longer need it.

Copies and backups of the CDF

A copy of the CDF is protected by the master password that was in use when the copy was made, not by your current one. Treat every copy like the CDF itself: the backups BroadSQL makes before a CDF upgrade (in conf/backups) and before a master-password change, and any copy you make yourself.

How BroadSQL keeps the CDF private

BroadSQL never connects to the CDF as an ordinary database. Its own configuration commands (CONFIG, ADD CONNECTION and the others) read and save the CDF directly. Every connection, test, export, linked table or monitoring file that BroadSQL opens is checked: one that would reach the CDF, under any name, path or copy, is refused before anything is opened or written. Direct SQL on the CDF is possible only in CDF maintenance mode, opened with CONNECT $CDF and the master password, typed again each time. See What the protection covers.

Passwords of your connections

SET PASSWORD changes the password of the account you are connected as, in the database itself, on H2, Apache Derby (with NATIVE authentication) and HSQLDB. It proves the change with a new connection before saving the new password in BroadSQL.

On every other database (Oracle, PostgreSQL, MySQL, MariaDB, SQL Server, Db2 and the others), change the password with the tools of that database or of your identity provider, then update the password BroadSQL saved with EDIT CONNECTION or in CONFIG. Saving a password in BroadSQL never changes it in the database.

Passwords are never written in BroadSQL's messages, activity log, application log or command history. The database itself may record statements in its own logs, outside BroadSQL's control.

Production databases

When a connection belongs to an Environment flagged Production, BroadSQL asks for a confirmation before a statement that can modify the database: every time, or once per connected session, as you choose with the setting ProductionConfirmEveryChange. Without an interactive terminal, such statements are refused. See Production confirmation.

This confirmation is a safety net against mistakes. It is not access control: the permissions of the database account remain the security boundary. Use an account with read-only rights where you only read.

Logging out

LOGOUT (or LOGOFF) locks BroadSQL without closing it: it closes every database connection, closes the Editor and the configuration windows, makes any database object still held by unfinished work unusable, forgets the connection history and the remembered connection, and drops the master password and the decrypted configuration it held. Nothing runs until the master password is typed again.

Java does not allow BroadSQL to erase text from memory: the master password and the passwords of your connections stay in the process memory, unreachable by BroadSQL, until that memory is reused. Someone able to read the memory of your running BroadSQL can read them; EXIT ends that exposure.

Files that may contain sensitive data

These files are not encrypted. Protect their folders with file permissions.

What you type at a password prompt is never kept in the history or the activity log. A password you write inside a SQL statement (for example CREATE USER ... PASSWORD '...') is part of the command, and is kept like any other command. See Command activity log and Exporting data.

LINK TABLE saves the remote connection's password in the definition of the linked table, inside the H2 database that holds it.

Code you run

Scripts, JavaScript scripts, RUNTIME CMD, extension commands and JDBC drivers run with your rights and can do anything you can do. Only run the ones you trust.

API calls

API requests use HTTPS when the URL does. Write credentials as environment-variable references (${ENV:NAME}) rather than values, in API definitions and in the proxy settings. Review a collection before importing it.

Verifying a download

Each release ZIP on the Downloads page has a SHA-256 checksum, shown in the table and in the file BroadSQL-<version>.zip.sha256 next to it. A matching checksum proves that your file is exactly the file published on broadsql.com, not damaged or altered on the way. It does not prove who published it, since it comes from the same site.

On Windows (PowerShell):

Get-FileHash BroadSQL-<version>.zip -Algorithm SHA256

or, in a command prompt:

certutil -hashfile BroadSQL-<version>.zip SHA256

On Linux or macOS, in the folder that holds both files:

sha256sum -c BroadSQL-<version>.zip.sha256

Compare the result with the value on the Downloads page (case does not matter). Releases up to 5.4.5 also keep their former SHA-1 file, .sha1.

Password managers

BroadSQL does not need a password manager. Integration with tools such as KeePassXC or gopass is a possible future improvement, not a feature of this release.

What BroadSQL does not do

• It does not transmit connection credentials anywhere except to the database they authenticate against, over the protocol of that database's JDBC driver. For TLS to your database, configure the driver as for any other JDBC client, usually with connection URL parameters.
• It does not phone home, collect usage telemetry, or contact any BroadSQL server during normal operation: see Third-party dependencies for everything bundled inside it.

Open, auditable source

The core of BroadSQL, the code that parses your commands and talks to your databases, is published separately at github.com/lico/broadsql-source, with its test suite. Read the code yourself, or build it and run the same tests.

That repository is a subset of the full project (internal release tooling and working documents are not included), published under the Apache License, Version 2.0. Its README and LICENSE cover only that excerpt, not the BroadSQL product itself (see License).

Reporting a security issue

If you find a security problem in BroadSQL, contact us directly rather than filing a public issue: see Contact.

Found something wrong or unclear on this page? Tell us, with the page address.