7.2 Installing SSL Certificates

Important

The self-signed certificates are generated by the installation or upgrade process, and are set to expire after 365 days. In the unlikely event you are running a version of MySQL Enterprise Service Manager using the default certificates for more than a year, you must generate new certificates. If you do not generate new certificates, the SSL connection between MySQL Enterprise Service Manager and the repository fails. This section describes how to generate those certificates.

These instructions guide you through the process of installing SSL certificates for your MySQL Enterprise Monitor installation.

Checking the Keystore

All certificates and keys are stored in the Tomcat keystore. To check the certificates stored in the keystore, run the following command:

keytool -keystore $INSTALL_ROOT/apache-tomcat/conf/keystore -list -v

Generating Keystore, Key, and Certificate

For information on using keytool, see Java Keytool.

To generate the certificate and add it to the default keystore, run the following command:

  $INSTALL_ROOT/java/bin/keytool -genkey -keyalg RSA -sigalg SHA256withRSA 
  -keystore $INSTALL_ROOT/apache-tomcat/conf/keystore -alias tomcat 
  -validity 365 -keysize 2048

This generates a 2048-bit, RSA private key, and certificate. This is the same command as used by MySQL Enterprise Monitor installers.

Important

When prompted for the key password, if you enter a password, rather than accepting the default by pressing Enter, you must also add the new password in the Tomcat configuration file, server.xml.

MySQL Enterprise Service Manager SSL Import

To install an SSL certificate for MySQL Enterprise Service Manager you must use the Java keytool to import the certificate into the keystore.

To import your certificate, run the following command:

      keytool -import -trustcacerts -alias mycertificate -file cert.pem -keystore keystore

If you want to import an existing certificate, which is password protected, you must convert it to a format understood by the Java keytool. The certificate must be converted from X509 to pkcs12 format using the openSSL toolkit and the following command:

        
        openssl pkcs12 -export -in [path-to-x509Cert]  -inkey [path-to-cert-private-key] 
        -out [path-to-cert-to-import-for-keystore] -name tomcat

Important

The certificate name must be set to tomcat, or match the name used in the key generation steps.

To import the converted certificate, run the following command:

      $INSTALL_ROOT/java/bin/keytool -importkeystore 
  -srckeystore [path-to-cert-to-import-for-keystore] -srcstoretype pkcs12 
  -destkeystore $INSTALL_ROOT/apache-tomcat/conf/keystore 
  -deststoretype jks -srcalias tomcat -destalias tomcat

Note

If you are replacing an existing certificate with a new certificate using the same name, you must delete the existing certificate before importing the new one.

For example, if replacing a certificate named tomcat, which is the default in MySQL Enterprise Monitor, you must run the keytool with -delete -name -tomcat before running the import command.

Restart the service manager. For more information about stopping and starting the service manager, see the instructions for Unix/Mac OS X and Microsoft Windows.

SSL for the Repository

For information on SSL and MySQL Server, see Creating SSL and RSA Certificates and Keys.

MySQL Enterprise Monitor Agent

To configure SSL-related options for the Agent, the following values may be placed in $INSTALL_ROOT/etc/bootstrap.properties:

Table 7.1 Agent SSL Configuration Options

Parameter	Description	Removed
`ssl-verify-hostnames`	Values: True or False (default). Verify that the hostname of the service manager that the Agent is connected to matches what is in the SSL certificate.
`ssl-allow-self-signed-certs`	Values:True (default) or False. If set to `true` self-signed certificates are permitted. If set to `false`, self-signed certificates are not permitted.
`ssl-verify-host-certs`	Values: True or False (default). To support self-signed certificates, a commercial certificate, or if the CA certificate has been imported into a keystore, set to true.	3.0.20
`ssl-ca-keystore-path`	Values: String Path to keystore with CA cert(s), if `ssl-allow-self-signed-certs` is true. This path must be defined as a URL. For example: `file:///Applications/mysql/enterprise/agent/etc/mykeystore`
`ssl-ca-keystore-password`	Values: String Password for the CA keystore, if `ssl-allow-self-signed-certs` is true.

An example bootstrap.properties SSL certification section:

ssl-verify-hostname=false
ssl-allow-self-signed-certs=true
ssl-ca-keystore-path=file:///Applications/mysql/enterprise/agent/etc/mykeystore
ssl-ca-keystore-password=password123

To import a CA certificate in PEM format to a new keystore on the Agent, execute the following:

$INSTALL_ROOT/java/bin/keytool -import -file /path/to/ca/ca.pem -alias CA_ALIAS -keystore $INSTALL_ROOT/etc/cacerts

The tool responds with the certificate details. For example:

Enter keystore password:  (the keystore requires at least a 6 character password)
Re-enter new password:

Owner: CN=serverName.com, O=MySQL AB, ST=Uppsala, C=SE
Issuer: O=MySQL AB, L=Uppsala, ST=Uppsala, C=SE
Serial number: 100002
Valid from: Fri Jan 29 12:56:49 CET 2010 until: Wed Jan 28 12:56:49 CET 2015
Certificate fingerprints:
     MD5:  E5:FB:56:76:78:B1:0C:D7:B0:80:9F:65:06:3E:48:3E
     SHA1: 87:59:80:28:CE:15:EF:7E:F1:75:4B:76:77:5E:64:EA:B7:1D:D1:18
     SHA256: F4:0B:79:52:CF:F3:A1:A4:7F:B2:D7:C1:65:60:F0:80:93:87:D2:68:9A:A1:
             84:F4:06:6E:8E:CF:C1:F6:1B:52
     Signature algorithm name: MD5withRSA
     Version: 1
Trust this certificate? [no]: (type yes + enter)
Certificate was added to keystore

You must edit the ssl-ca-* configuration values in bootstrap.properties accordingly, to use the path to the keystore and password.

LDAP SSL Configuration

SSL configuration for LDAP is configured at the Java VM level. That is, it is configured in the keystore of the Java VM bundled with your MySQL Enterprise Monitor installation.

Important

The JVM shipped with MySQL Enterprise Service Manager does not support the AES256 cipher. This can prevent you using LDAP servers which implement that cipher.

To connect to LDAP servers which implement the AES256 cipher, you must download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 package. This package is available from: Java Cryptography Extension.

The steps described in this section assume your LDAP server is correctly configured and you have a root CA certificate which was used to generate the LDAP server's certificate.

To enable SSL for LDAP and MySQL Enterprise Service Manager, you must do the following:

Convert the LDAP server's root CA certificate from PEM to DER format, if necessary. If the CA certificate is already in DER format, continue to the next step.
```
  openssl x509 -in cacert.pem -inform PEM -out ~/cacert.der -outform DER
```
Import the CA certificate, in DER format, into the MySQL Enterprise Service Manager Java keystore. Run the following command from the bin directory of your MySQL Enterprise Service Manager's Java installation:
```
  keytool -import -trustcacerts -alias ldapssl -file ~/cacert.der -keystore lib/security/cacerts
```
Restart MySQL Enterprise Service Manager with the following command:
```
  mysql/enterprise/monitor/mysqlmonitorctl.sh restart
```