3.5.9.1 Setting up Server Authentication

For 8.0.12 and earlier: Server authentication via server certificate verification is enabled when the Connector/J connection properties useSSL AND verifyServerCertificate are both true. Hostname verification is not supported—host authentication is by certificates only.

For 8.0.13 and later: Server authentication via server certificate verification is enabled when the Connector/J connection property sslMode is set to VERIFY_CA or VERIFY_IDENTITY. If sslMode is not set, server authentication via server certificate verification is enabled when the legacy properties useSSL AND verifyServerCertificate are both true.

Certificates signed by a trusted CA.  When server authentication via server certificate verification is enabled, if no additional configurations are made regarding server authentication, Java verifies the server certificate using its default trusted CA certificates, usually from $JAVA_HOME/lib/security/cacerts.

Using self-signed certificates.  It is pretty common though for MySQL server certificates to be self-signed or signed by a self-signed CA certificate; the auto-generated certificates and keys created by the MySQL server are based on the latter—that is, the server generates all required keys and a self-signed CA certificate that is used to sign a server and a client certificate. The server then configures itself to use the CA certificate and the server certificate. Although the client certificate file is placed in the same directory, it is not used by the server.

To verify the server certificate, Connector/J needs to be able to read the certificate that signed it, that is, the server certificate that signed itself or the self-signed CA certificate. This can be accomplished by either importing the certificate (ca.pem or any other certificate) into the Java default truststore (although tampering the default truststore is not recommended) or by importing it into a custom Java truststore file and configuring the Connector/J driver accordingly. Use Java's keytool (typically located in the bin subdirectory of your JDK or JRE installation) to import the server certificates:

$> keytool -importcert -alias MySQLCACert -file ca.pem \
    -keystore truststore -storepass mypassword

Supply the proper arguments for the command options. If the truststore file does not already exist, a new one will be created; otherwise the certificate will be added to the existing file. Interaction with keytool looks like this:

Owner: CN=MySQL_Server_5.7.17_Auto_Generated_CA_Certificate
Issuer: CN=MySQL_Server_5.7.17_Auto_Generated_CA_Certificate
Serial number: 1
Valid from: Thu Feb 16 11:42:43 EST 2017 until: Sun Feb 14 11:42:43 EST 2027
Certificate fingerprints:
	 MD5:  18:87:97:37:EA:CB:0B:5A:24:AB:27:76:45:A4:78:C1
	 SHA1: 2B:0D:D9:69:2C:99:BF:1E:2A:25:4E:8D:2D:38:B8:70:66:47:FA:ED
	 SHA256: C3:29:67:1B:E5:37:06:F7:A9:93:DF:C7:B3:27:5E:09:C7:FD:EE:2D:18:86:F4:9C:40:D8:26:CB:DA:95:A0:24
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 1
Trust this certificate? [no]:  yes
Certificate was added to keystore

The output of the command shows all details about the imported certificate. Make sure you remember the password you have supplied. Also, be mindful that the password will have to be written as plain text in your Connector/J configuration file or application source code.

The next step is to configure Java or Connector/J to read the truststore you just created or modified. This can be done by using one of the following three methods:

1. Using the Java command line arguments:

   -Djavax.net.ssl.trustStore=path_to_truststore_file 
   -Djavax.net.ssl.trustStorePassword=mypassword

2. Setting the system properties directly in the client code:

   System.setProperty("javax.net.ssl.trustStore","path_to_truststore_file"); 
   System.setProperty("javax.net.ssl.trustStorePassword","mypassword");

3. Setting the Connector/J connection properties:

   trustCertificateKeyStoreUrl=file:path_to_truststore_file 
   trustCertificateKeyStorePassword=mypassword

Notice that when used together, the connection properties override the values set by the other two methods. Also, whatever values set with connection properties are used in that connection only, while values set using the system-wide values are used for all connections (unless overridden by the connection properties). For Connector/J 8.0.22 and later: Setting the connection property fallbackToSystemTrustStore to false prevents Connector/J from falling back to the system-wide truststore setup you created using method (1) or (2) when method (3) is not used.

With the above setup and the server authentication enabled, all connections established are going to be SSL-encrypted, with the server being authenticated in the SSL handshake process, and the client can now safely trust the server it is connecting to.

For X-Protocol connections, the connection properties xdevapi.ssl-truststore, xdevapi.ssl-truststore-type, xdevapi.ssl-truststore-password, and xdevapi.ssl-fallbackToSystemTrustStore specify the truststore settings, just like trustCertificateKeyStoreUrl, trustCertificateKeyStoreType, trustCertificateKeyStorePasswordamd fallbackToSystemTrustStore do for MySQL-protocol connections; if not explicitly set, xdevapi.ssl-truststore, xdevapi.ssl-truststore-type, xdevapi.ssl-truststore-password, and xdevapi.ssl-fallbackToSystemTrustStore take up the values of trustCertificateKeyStoreUrl, trustCertificateKeyStoreType, trustCertificateKeyStorePassword, and fallbackToSystemTrustStore respectively.

Service Identity Verification.  For 8.0.13 and later: Beyond server authentication via server certificate verification, when sslMode is set to VERIFY_IDENTITY, Connector/J also performs host name identity verification by checking whether the host name that it uses for connecting matches the Common Name value in the server certificate.