PDF (US Ltr)
- 4.5Mb
PDF (A4)
- 4.5Mb
Connector/J can encrypt all data communicated between the JDBC driver and the server (except for the initial handshake) using SSL. There is a performance penalty for enabling connection encryption, the severity of which depends on multiple factors including (but not limited to) the size of the query, the amount of data returned, the server hardware, the SSL library used, the network bandwidth, and so on.
The system works through two Java keystore files: one file
contains the certificate information for the server
(truststore in the examples below), and
another contains the keys and certificate for the client
(keystore in the examples below). All Java
keystore files are protected by the password supplied to the
keytool when you created the files. You need
the file names and the associated passwords to create an SSL
connection.
For SSL support to work, you must have the following:
A MySQL server that supports SSL, and compiled and configured to do so. For more information, see Using Encrypted Connections and Configuring SSL Library Support.
A signed client certificate, if using mutual (two-way) authentication.
By default, Connector/J establishes secure connections with the MySQL servers. Note that MySQL servers 5.7 and up, when compiled with OpenSSL, can automatically generate missing SSL files at startup and configure the SSL connection accordingly.
For 8.0.12 and earlier: As long as the
server is correctly configured to use SSL, there is no need to
configure anything on the Connector/J client to use encrypted
connections (the exception is when Connector/J is connecting to
very old server versions like 5.6.25 and earlier or 5.7.5 and
earlier, in which case the client must set the connection
property useSSL=true in order to use
encrypted connections). The client can demand SSL to be used by
setting the connection property
requireSSL=true; the connection then fails if
the server is not configured to use SSL. Without
requireSSL=true, the connection just falls
back to non-encrypted mode if the server is not configured to
use SSL.
For 8.0.13 and later: As long as the server
is correctly configured to use SSL, there is no need to
configure anything on the Connector/J client to use encrypted
connections. The client can demand SSL to be used by setting the
connection property sslMode=REQUIRED,
VERIFY_CA, or
VERIFY_IDENTITY; the connection then fails if
the server is not configured to use SSL. With
sslMode=PREFERRED, the connection just falls
back to non-encrypted mode if the server is not configured to
use SSL. For X-Protocol connections, the connection property
xdevapi.ssl-mode specifies the SSL Mode
setting, just like sslMode does for
MySQL-protocol connections (except that
PREFERRED is not supported by X Protocol); if
not explicitly set, xdevapi.ssl-mode takes up
the value of sslMode ( if
xdevapi.ssl-mode is not set and
sslMode is set to
PREFERRED,
xdevapi.ssl-mode is set to
REQUIRED).
For additional security, you can setup the client for a one-way (server or client) or two-way (server and client) SSL authentication, allowing the client or the server to authenticate each other's identity.
TLS versions: The allowable versions of TLS
protocol can be restricted using the connection properties
tlsVersions and, for X DevAPI connections
and for release 8.0.19 and later,
xdevapi.tls-versions (when
xdevapi.tls-versions is not specified, it
takes up the value of tlsVersions). If no
such restrictions have been specified, Connector/J attempts to
connect to the server with the TLSv1.2 and TLSv1.3.
Notes
Since Connector/J 8.0.28, the connection property
enabledTLSProtocolshas been renamed totlsVersions, andenabledSSLCipherSuiteshas been renamed totlsCiphersuites; the original names remain as aliases.For Connector/J 8.0.26 and later: TLSv1 and TLSv1.1 were deprecated in Connector/J 8.0.26 and removed in release 8.0.28; the removed values are considered invalid for use with connection options and session settings. Connections can be made using the more-secure TLSv1.2 and TLSv1.3 protocols. Using TLSv1.3 requires that the server be compiled with OpenSSL 1.1.1 or higher and Connector/J be run with a JVM that supports TLSv1.3 (for example, Oracle Java 8u261 and above).
For Connector/J 8.0.18 and earlier when connecting to MySQL Community Server 5.6 and 5.7 using the JDBC API: Due to compatibility issues with MySQL Server compiled with yaSSL, Connector/J does not enable connections with TLSv1.2 and higher by default. When connecting to servers that restrict connections to use those higher TLS versions, enable them explicitly by setting the Connector/J connection property
enabledTLSProtocols(e.g., setenabledTLSProtocols=TLSv1.2,TLSv1.3).
Cipher Suites: Since release 8.0.19, the
cipher suites usable by Connector/J are pre-restricted by a
properties file that can be found at
src/main/resources/com/mysql/cj/TlsSettings.properties
inside the src folder on the source tree or
in the platform-independent distribution archive (in
.tar.gz or .zip
format) for Connector/J. The file contains four sections,
listing in each the mandatory, approved, deprecated, and
unacceptable ciphers. Only suites listed in the first three
sections can be used. The last section (unacceptable) defines
patterns or masks that blocklist unsafe cipher suites.
Practically, with the allowlist already given in the first three
sections, the blocklist patterns in the forth section are
redundant; but they are there as an extra safeguard against
unwanted ciphers. The allowlist and blocklist of cipher suites
apply to both JDBC and X DevAPI connections.
The allowable cipher suites for SSL connections can be
restricted using the connection properties
tlsCiphersuites and, for X DevAPI
connections and for release 8.0.19 and later,
xdevapi.tls-ciphersuites (when
xdevapi.tls-ciphersuites is not specified, it
takes up the value of tlsCiphersuites). If no
such restrictions have been specified, Connector/J attempts to
establish SSL connections with any allowlisted cipher suites
that the server accepts.