4.3.4 Using Encrypted Connections

Using encrypted connections is possible when connecting to a TLS (sometimes referred to as SSL) enabled MySQL server. Much of the configuration of MySQL Shell is based on the options used by MySQL server, see Using Encrypted Connections for more information.

To configure an encrypted connection at startup of MySQL Shell, use the following command options:

• --ssl-mode : This option specifies the desired security state of the connection to the server.

• --ssl-ca=file_name: The path to a file in PEM format that contains a list of trusted SSL Certificate Authorities.

• --ssl-capath=dir_name: The path to a directory that contains trusted SSL Certificate Authority certificates in PEM format.

• --ssl-cert=file_name: The name of the SSL certificate file in PEM format to use for establishing an encrypted connection.

• --ssl-cipher=name: The name of the SSL cipher to use for establishing an encrypted connection.

• --ssl-key=file_name: The name of the SSL key file in PEM format to use for establishing an encrypted connection.

• --ssl-crl=name: The path to a file containing certificate revocation lists in PEM format.

• --ssl-crlpath=dir_name: The path to a directory that contains files containing certificate revocation lists in PEM format.

• --tls-ciphersuites=suites: The TLS cipher suites permitted for encrypted connections, specified as a colon separated list of TLS cipher suite names. For example --tls-ciphersuites=TLS_DHE_PSK_WITH_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256.

• --tls-version=version: The TLS protocols permitted for encrypted connections, specified as a comma separated list. For example --tls-version=TLSv1.2,TLSv1.3.

  From MySQL 8.0.28, the TLSv1 and TLSv1.1 protocols are not supported by MySQL Server, and MySQL Shell cannot make a TLS/SSL connection with the protocol set to TLSv1 or TLSv1.1. If you attempt to make a connection using TLS/SSL from any version of MySQL Shell to a MySQL Server instance at 8.0.28 or above, and you specify the TLSv1 or TLSv1.1 protocol using the--tls-version option, you will see the following results:

  • For TCP connections, the connection fails, and an error is returned to MySQL Shell.

  • For socket connections, if --ssl-mode is set to REQUIRED, the connection fails. If --ssl-mode is not set to REQUIRED, the connection is made but with TLS/SSL disabled.

  The TLSv1 and TLSv1.1 protocols were deprecated from MySQL 8.0.26. For background, refer to the IETF memo Deprecating TLSv1.0 and TLSv1.1. Make connections between MySQL Shell and MySQL Server using the more-secure TLSv1.2 and TLSv1.3 protocols. TLSv1.3 requires that both the MySQL server and the client application be compiled with OpenSSL 1.1.1 or higher. For more information on the support for TLS protocol versions in MySQL Server releases, see Removal of Support for the TLSv1 and TLSv1.1 Protocols.

• --tls-kex==[key_exchange_list]: Specifies a colon-separated list of TLS key exchange groups the client may use. Allowed names are X25519, secp384r1, secp256r1, secp521r1. For OpenSSL 3.5.0, or higher, you can also use X25519MLKEM768, secp384r1MLKEM1024, secp256r1MLKEM768, MLKEM512, and MLKEM768.

  Group names are case-sensitive. MySQL Shell passes the value unchanged to the selected client library. If the option is omitted, the client library uses its default groups.

  See Post-Quantum Cryptography.

• --force-pqc: Boolean option that requires negotiation of a PQC-capable TLS key-exchange group. The default is false. This option does not by itself require an encrypted TLS 1.3 connection; specify ssl-mode=REQUIRED and tls-version=TLSv1.3 if those properties are required.

  See Post-Quantum Cryptography.

• --use-pqc-sign: Boolean option that enables the client library to advertise PQC-capable TLS handshake signature algorithms. The default is false. Enabling the option does not guarantee selection of a PQC signature algorithm.

  See Post-Quantum Cryptography.

Alternatively, the SSL options can be encoded as part of a URI-like connection string as part of the query element. The available SSL options are the same as those listed above, but written without the preceding hyphens. For example, ssl-ca is the equivalent of --ssl-ca.

Paths specified in a URI-like string must be percent encoded, for example:

ssluser@127.0.0.1?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
.pem

See Connecting to the Server Using URI-Like Strings or Key-Value Pairs for more information.

To establish an encrypted connection for a scripting session in JavaScript or Python mode, set the SSL information in the connectionData dictionary. For example:

mysql-js> var session=mysqlx.getSession({host: 'localhost',
                                             user: 'root',
                                             password: 'password',
                                             ssl_ca: "path_to_ca_file",
                                             ssl_cert: "path_to_cert_file",
                                             ssl_key: "path_to_key_file"});

Sessions created using mysqlx.getSession(), mysql.getSession(), or mysql.getClassicSession() use ssl-mode=REQUIRED as the default if no ssl-mode is provided, and neither ssl-ca nor ssl-capath is provided. If no ssl-mode is provided and any of ssl-ca or ssl-capath is provided, created sessions default to ssl-mode=VERIFY_CA.

See Connecting Using Key-Value Pairs for more information.

Post-Quantum Cryptography for TLS 1.3

MySQL Shell supports PQC-capable TLS key exchange and TLS handshake signatures for both classic MySQL protocol and X Protocol connections. PQC algorithms require TLS 1.3 and a client library built with OpenSSL 3.5 or later.

The following options are available:

• --tls-kex: (String) Specifies a colon-separated list of permitted TLS key-exchange groups. MySQL Shell passes the value unchanged to the client library.

• --force-pqc: (Boolean) Requires the client library to negotiate a PQC-capable key-exchange group. Connection establishment fails if such a group cannot be used.

• --use-pqc-sign: (Boolean) Allows the client library to advertise PQC-capable TLS handshake signature algorithms. Enabling this option does not guarantee that a PQC signature algorithm is selected.

Key-exchange group names are case-sensitive. MySQL Shell does not validate the names or alter their spelling or case.

The options can be specified in the following ways:

• Commandline:

  mysqlsh --mysql \
    --uri user@host:3306 \
    --ssl-mode=REQUIRED \
    --tls-version=TLSv1.3 \
    --force-pqc \
    --tls-kex=X25519MLKEM768:secp384r1MLKEM1024

• URI query attributes:

  mysql://user@host:3306?ssl-mode=REQUIRED&tls-version=TLSv1.3&force-pqc=true&tls-kex=X25519MLKEM768
  or
  mysqlx://user@host:33060?ssl-mode=REQUIRED&tls-version=TLSv1.3&force-pqc=true

• Dictionary connection

  shell.connect({
      "scheme": "mysqlx",
      "user": "user",
      "host": "host",
      "port": 33060,
      "ssl-mode": "REQUIRED",
      "tls-version": "TLSv1.3",
      "force-pqc": True,
      "tls-kex": "X25519MLKEM768",
      "use-pqc-sign": True
  })