By default, Skeema will use an encrypted connection whenever the database server supports one, or an unencrypted connection if not. This behavior can be configured with Skeema’s ssl-mode option.
All SSL/TLS options are designed to match the names and behavior of their corresponding mysql or mariadb command-line client options. This means if you’ve already configured them in your ~/my.cnf file, Skeema will pick up these settings automatically by default.
To establish an encrypted connection to an older server version, such as MySQL 5.x or MariaDB 10.1, be sure to use Skeema v1.12.2+. When specifically communicating with an older server, Skeema now relaxes some of Golang’s recent TLS client-side defaults as needed, to ensure compatibility of TLS version and cipher suites.
All editions of Skeema are capable of using an encrypted connection. This includes the ability to connect with a user account that has the REQUIRE SSL attribute on the server.
Several additional options relating to encrypted connections are only available in the Premium edition of the Skeema CLI. The rest of this page describes these Premium features.
Using certificate options
Several Premium options (ssl-cert, ssl-key, ssl-ca, server-public-key-path) allow you to supply a path to a certificate file. The supplied file must be in PEM format. The option value should include the full file name of the .pem file.
You can use either absolute or relative paths for these options. When supplying them on the command-line, a relative path will be interpreted based on the working directory from which skeema was initially invoked. When setting them in an option file, a relative path will be interpreted based on the directory containing that option file.
Client-side certificates
Premium options ssl-cert and ssl-key may be specified to supply client-side public and private keys, respectively. This permits connecting to the database with a user account that has the REQUIRE X509, REQUIRE ISSUER, and/or REQUIRE SUBJECT attributes on the server side.
If you set ssl-cert, you must also set ssl-key, and vice versa. See Using certificate options, above, to learn how to configure these options.
Certificate Authorities
The ssl-ca Premium option may be specified to supply a Certificate Authority (CA) file, which is used to verify the database server’s certificate. This helps to confirm that the server is the intended destination and not a man-in-the-middle attacker.
See Using certificate options, above, to learn how to configure this option.
If no ssl-mode is specified, but an ssl-ca is supplied, ssl-mode=verify_ca will be used automatically: the server’s cert will be verified, but no strict server hostname verification is performed.
To improve security further, use ssl-mode=verify_identity to perform a stricter CA check which includes verification of the server’s hostname against Skeema’s host option. (For purposes of compatibility with MariaDB clients and older MySQL clients, this behavior can also be enabled using the equivalent ssl-verify-server-cert boolean option.)
If the server has a self-signed certificate, the stricter server host identity verification cannot be used.
Suppling ssl-ca has no useful effect when combined with an explicit setting of ssl-mode=disabled, ssl-mode=preferred, or ssl-mode=required. These modes do not perform any verification of the server.
Secure password exchange without SSL/TLS
When connecting to a MySQL database server using an unencrypted connection (ssl-mode=disabled, or ssl-mode=preferred with a server that does not support SSL) and an authentication plugin of either sha256_password or caching_sha2_password, the server ordinarily sends a special-purpose RSA public key to the client to use for password encryption.
This public key transfer has security implications (man-in-the-middle risk), and incurs an extra round-trip at connection time. To avoid this, place the server’s RSA public key on each client machine. In order to obtain the correct RSA public key from the server, query server variable caching_sha2_password_public_key_path to see the file path on the server side. Typically this defaults to /var/lib/mysql/public_key.pem.
Once you have placed the RSA public key on the client machines, configure its location in Skeema using server-public-key-path. See Using certificate options, above, to learn how to configure this option.
This option has no effect with an encrypted connection, or when the database user is configured with an authentication plugin other than sha256_password or caching_sha2_password on the database server. Typically this depends on the server flavor/version:
- In MySQL 8.0+,
caching_sha2_passwordis the default auth plugin. - In MySQL 5.7,
sha256_passwordis available, but is not used by default. - In MariaDB 12.1+,
caching_sha2_passwordcan optionally be enabled by loading the ‘auth_mysql_sha2’ plugin, followed by a server restart to generate the RSA key pair. Prior versions of MariaDB do not ship with this plugin.
SSH tunnels and ssl-mode
When using an SSH tunnel, if no ssl-mode has been configured, the SSL mode will default to disabled instead of the usual default of preferred. This is done to prevent unnecessary double-encryption, since the SSH tunnel is already encrypted.
To override this behavior, for example if you need to connect with a database user account that has the REQUIRE SSL attribute on the server side, you can explicitly set ssl-mode to either “required”, “verify_ca”, or “verify_identity”. However, be aware that the double-encryption will increase latency.