### 17.3.1 Setting Up Replication to Use Encrypted Connections

 To use an encrypted connection for the transfer of the binary log required during replication, both the source and the replica servers must support encrypted network connections. If either server does not support encrypted connections (because it has not been compiled or configured for them), replication through an encrypted connection is not possible.

 Setting up encrypted connections for replication is similar to doing so for client/server connections. You must obtain (or create) a suitable security certificate that you can use on the source, and a similar certificate (from the same certificate authority) on each replica. You must also obtain suitable key files.

 For more information on setting up a server and client for encrypted connections, see [Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”](using-encrypted-connections.html).

 To enable encrypted connections on the source, you must create or obtain suitable certificate and key files, and then add the following configuration parameters to the source's configuration within the `[mysqld]` section of the source's `my.cnf` file, changing the file names as necessary:

```
[mysqld]
ssl_ca=cacert.pem
ssl_cert=server-cert.pem
ssl_key=server-key.pem
```

 The paths to the files may be relative or absolute; we recommend that you always use complete paths for this purpose.

 The configuration parameters are as follows:

* [`ssl_ca`](server-system-variables.html#sysvar_ssl_ca): The path name of the Certificate Authority (CA) certificate file. ([`ssl_capath`](server-system-variables.html#sysvar_ssl_capath) is similar but specifies the path name of a directory of CA certificate files.)

* [`ssl_cert`](server-system-variables.html#sysvar_ssl_cert): The path name of the server public key certificate file. This certificate can be sent to the client and authenticated against the CA certificate that it has.

* [`ssl_key`](server-system-variables.html#sysvar_ssl_key): The path name of the server private key file.

 To enable encrypted connections on the replica, use the [`CHANGE REPLICATION SOURCE TO`](change-replication-source-to.html) statement (from MySQL 8.0.23) or [`CHANGE MASTER TO`](change-master-to.html) statement (before MySQL 8.0.23). You can either name the replica's certificate and SSL private key files required for the encrypted connection in the `[client]` section of the replica's `my.cnf` file, or you can explicitly specify that information using the [`CHANGE REPLICATION SOURCE TO`](change-replication-source-to.html) | [`CHANGE MASTER TO`](change-master-to.html) statement.

* To name the replica's certificate and key files using an option file, add the following lines to the `[client]` section of the replica's `my.cnf` file, changing the file names as necessary:

  ```
  [client]
  ssl-ca=cacert.pem
  ssl-cert=client-cert.pem
  ssl-key=client-key.pem
  ```

* Restart the replica server, using the [`--skip-slave-start`](replication-options-replica.html#option_mysqld_skip-slave-start) option, or from MySQL 8.0.24, the [`skip_slave_start`](replication-options-replica.html#sysvar_skip_slave_start) system variable, to prevent the replica from connecting to the source. Use [`CHANGE REPLICATION SOURCE TO`](change-replication-source-to.html) | [`CHANGE MASTER TO`](change-master-to.html) to specify the source configuration, and add the `MASTER_SSL` option to connect using encryption:

  ```
  mysql> CHANGE MASTER TO
      -> MASTER_HOST='source_hostname',
      -> MASTER_USER='repl',
      -> MASTER_PASSWORD='password',
      -> MASTER_SSL=1;

  Or from MySQL 8.0.23:
  mysql> CHANGE REPLICATION SOURCE TO
      -> SOURCE_HOST='source_hostname',
      -> SOURCE_USER='repl',
      -> SOURCE_PASSWORD='password',
      -> SOURCE_SSL=1;
  ```

   Setting `SOURCE_SSL=1` | `MASTER_SSL=1` for a replication connection and then setting no further `SOURCE_SSL_*`xxx`*` | `MASTER_SSL_*`xxx`*` options corresponds to setting `--ssl-mode=REQUIRED` for the client, as described in [Command Options for Encrypted Connections](connection-options.html#encrypted-connection-options). With `SOURCE_SSL=1` | `MASTER_SSL=1`, the connection attempt only succeeds if an encrypted connection can be established. A replication connection does not fall back to an unencrypted connection, so there is no setting corresponding to the `--ssl-mode=PREFERRED` setting for replication. If `SOURCE_SSL=0` | `MASTER_SSL=0` is set, this corresponds to `--ssl-mode=DISABLED`.

* To name the replica's certificate and SSL private key files using the [`CHANGE REPLICATION SOURCE TO`](change-replication-source-to.html) | [`CHANGE MASTER TO`](change-master-to.html) statement, if you did not do this in the replica's `my.cnf` file, add the appropriate `SOURCE_SSL_*`xxx`*` | `MASTER_SSL_*`xxx`*` options:

  ```
      -> MASTER_SSL_CA = 'ca_file_name',
      -> MASTER_SSL_CAPATH = 'ca_directory_name',
      -> MASTER_SSL_CERT = 'cert_file_name',
      -> MASTER_SSL_KEY = 'key_file_name',
  ```

   These options correspond to the `--ssl-*`xxx`*` options with the same names, as described in [Command Options for Encrypted Connections](connection-options.html#encrypted-connection-options). For these options to take effect, `MASTER_SSL=1` must also be set. For a replication connection, specifying a value for either of ` MASTER_SSL_CA` or `MASTER_SSL_CAPATH`, or specifying these options in the replica's `my.cnf` file, corresponds to setting `--ssl-mode=VERIFY_CA`. The connection attempt only succeeds if a valid matching Certificate Authority (CA) certificate is found using the specified information.

* To activate host name identity verification, add the `MASTER_SSL_VERIFY_SERVER_CERT` option:

  ```
      -> MASTER_SSL_VERIFY_SERVER_CERT=1,
  ```

   This option corresponds to the `--ssl-verify-server-cert` option, which was deprecated from MySQL 5.7 and removed in MySQL 8.0. For a replication connection, specifying `MASTER_SSL_VERIFY_SERVER_CERT=1` corresponds to setting `--ssl-mode=VERIFY_IDENTITY`, as described in [Command Options for Encrypted Connections](connection-options.html#encrypted-connection-options). For this option to take effect, `MASTER_SSL=1` must also be set. Host name identity verification does not work with self-signed certificates.

* To activate certificate revocation list (CRL) checks, add the `MASTER_SSL_CRL` or `MASTER_SSL_CRLPATH` option:

  ```
      -> MASTER_SSL_CRL = 'crl_file_name',
      -> MASTER_SSL_CRLPATH = 'crl_directory_name',
  ```

   These options correspond to the `--ssl-*`xxx`*` options with the same names, as described in [Command Options for Encrypted Connections](connection-options.html#encrypted-connection-options). If they are not specified, no CRL checking takes place.

* To specify lists of ciphers, ciphersuites, and encryption protocols permitted by the replica for the replication connection, use the `MASTER_SSL_CIPHER`, `MASTER_TLS_VERSION`, and `MASTER_TLS_CIPHERSUITES` options:

  ```
      -> MASTER_SSL_CIPHER = 'cipher_list',
      -> MASTER_TLS_VERSION = 'protocol_list',
      -> MASTER_TLS_CIPHERSUITES = 'ciphersuite_list',
  ```

  * The `MASTER_SSL_CIPHER` option specifies a colon-separated list of one or more ciphers permitted by the replica for the replication connection.

  * The `MASTER_TLS_VERSION` option specifies a comma-separated list of the TLS encryption protocols permitted by the replica for the replication connection, in a format like that for the [`tls_version`](server-system-variables.html#sysvar_tls_version) server system variable. The connection procedure negotiates the use of the highest TLS version that both the source and the replica permit. To be able to connect, the replica must have at least one TLS version in common with the source.

  * The `MASTER_TLS_CIPHERSUITES` option (available from MySQL 8.0.19) specifies a colon-separated list of one or more ciphersuites that are permitted by the replica for the replication connection if TLSv1.3 is used for the connection. If this option is set to `NULL` when TLSv1.3 is used (which is the default if you do not set the option), the ciphersuites that are enabled by default are allowed. If you set the option to an empty string, no cipher suites are allowed, and TLSv1.3 is therefore not used.

   The protocols, ciphers, and ciphersuites that you can specify in these lists depend on the SSL library used to compile MySQL. For information about the formats, the permitted values, and the defaults if you do not specify the options, see [Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”](encrypted-connection-protocols-ciphers.html).

  Note

   In MySQL 8.0.16 through 8.0.18, MySQL supports TLSv1.3, but the `MASTER_TLS_CIPHERSUITES` option is not available. In these releases, if TLSv1.3 is used for connections between a source and replica, the source must permit the use of at least one TLSv1.3 ciphersuite that is enabled by default. From MySQL 8.0.19, you can use the option to specify any selection of ciphersuites, including only non-default ciphersuites if you want.

* After the source information has been updated, start the replication process on the replica:

  ```
  mysql> START SLAVE;
  Or from MySQL 8.0.22:
  mysql> START REPLICA;
  ```

   You can use the [`SHOW REPLICA STATUS`](show-replica-status.html) (or before MySQL 8.0.22, [`SHOW SLAVE STATUS`](show-slave-status.html)) statement to confirm that an encrypted connection was established successfully.

* Requiring encrypted connections on the replica does not ensure that the source requires encrypted connections from replicas. If you want to ensure that the source only accepts replicas that connect using encrypted connections, create a replication user account on the source using the `REQUIRE SSL` option, then grant that user the [`REPLICATION SLAVE`](privileges-provided.html#priv_replication-slave) privilege. For example:

  ```
  mysql> CREATE USER 'repl'@'%.example.com' IDENTIFIED BY 'password'
      -> REQUIRE SSL;
  mysql> GRANT REPLICATION SLAVE ON *.*
      -> TO 'repl'@'%.example.com';
  ```

   If you have an existing replication user account on the source, you can add `REQUIRE SSL` to it with this statement:

  ```
  mysql> ALTER USER 'repl'@'%.example.com' REQUIRE SSL;
  ```

