Docs: Features: SSL/TLS Certificates

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.

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 public key to the client to use for password encryption.

This transfer is potentially insecure, and incurs an extra round-trip at connection time. To avoid this, place the public key on each client machine and then 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 useful effect if encrypted connections are known to be in-use. It also has no effect when connecting to a MariaDB server, since MariaDB does not support the sha256_password or caching_sha2_password authentication plugins.

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.