<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h3 class="title">
      <a name="using-encrypted-connections">
      </a>
      8.3.1 Configuring MySQL to Use Encrypted Connections
     </h3>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045247175632">
  </a>
  <a class="indexterm" name="idm46045247174592">
  </a>
  <a class="indexterm" name="idm46045247173120">
  </a>
  <p>
   Several configuration parameters are available to indicate whether
      to use encrypted connections, and to specify the appropriate
      certificate and key files. This section provides general guidance
      about configuring the server and clients for encrypted
      connections:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="using-encrypted-connections.html#using-encrypted-connections-server-side-startup-configuration" title="Server-Side Startup Configuration for Encrypted Connections">
       Server-Side Startup Configuration for Encrypted Connections
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="using-encrypted-connections.html#using-encrypted-connections-server-side-runtime-configuration" title="Server-Side Runtime Configuration and Monitoring for Encrypted Connections">
       Server-Side Runtime Configuration and Monitoring for Encrypted
Connections
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="using-encrypted-connections.html#using-encrypted-connections-client-side-configuration" title="Client-Side Configuration for Encrypted Connections">
       Client-Side Configuration for Encrypted Connections
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="using-encrypted-connections.html#enforce-certificate-validation" title="Configuring Certificate Validation Enforcement">
       Configuring Certificate Validation Enforcement
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="using-encrypted-connections.html#mandatory-encrypted-connections" title="Configuring Encrypted Connections as Mandatory">
       Configuring Encrypted Connections as Mandatory
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   Encrypted connections also can be used in other contexts, as
      discussed in these additional sections:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Between source and replica replication servers. See
      <a class="xref" href="replication-encrypted-connections.html" title="19.3.1 Setting Up Replication to Use Encrypted Connections">
       Section 19.3.1, “Setting Up Replication to Use Encrypted Connections”
      </a>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Among Group Replication servers. See
      <a class="xref" href="group-replication-secure-socket-layer-support-ssl.html" title="20.6.2 Securing Group Communication Connections with Secure Socket Layer (SSL)">
       Section 20.6.2, “Securing Group Communication Connections with Secure Socket Layer (SSL)”
      </a>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      By client programs that are based on the MySQL C API. See
      <a class="ulink" href="/doc/c-api/8.4/en/c-api-encrypted-connections.html" target="_top">
       Support for Encrypted Connections
      </a>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   Instructions for creating any required certificate and key files
      are available in
   <a class="xref" href="creating-ssl-rsa-files.html" title="8.3.3 Creating SSL and RSA Certificates and Keys">
    Section 8.3.3, “Creating SSL and RSA Certificates and Keys”
   </a>
   .
  </p>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="using-encrypted-connections-server-side-startup-configuration">
       </a>
       Server-Side Startup Configuration for Encrypted Connections
      </h4>
     </div>
    </div>
   </div>
   <p>
    To require that clients connect using encrypted connections,
        enable the
    <a class="link" href="server-system-variables.html#sysvar_require_secure_transport">
     <code class="literal">
      require_secure_transport
     </code>
    </a>
    system
        variable. See
    <a class="xref" href="using-encrypted-connections.html#mandatory-encrypted-connections" title="Configuring Encrypted Connections as Mandatory">
     Configuring Encrypted Connections as Mandatory
    </a>
    .
   </p>
   <p>
    These system variables on the server side specify the
        certificate and key files the server uses when permitting
        clients to establish encrypted connections:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_ssl_ca">
        <code class="literal">
         ssl_ca
        </code>
       </a>
       : The path name of
            the Certificate Authority (CA) certificate file.
            (
       <a class="link" href="server-system-variables.html#sysvar_ssl_capath">
        <code class="literal">
         ssl_capath
        </code>
       </a>
       is similar but
            specifies the path name of a directory of CA certificate
            files.)
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
        <code class="literal">
         ssl_cert
        </code>
       </a>
       : 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.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_ssl_key">
        <code class="literal">
         ssl_key
        </code>
       </a>
       : The path name of
            the server private key file.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For example, to enable the server for encrypted connections,
        start it with these lines in the
    <code class="filename">
     my.cnf
    </code>
    file, changing the file names as necessary:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa82085773"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">ssl_ca</span><span class="token attr-value"><span class="token punctuation">=</span>ca.pem</span>
<span class="token constant">ssl_cert</span><span class="token attr-value"><span class="token punctuation">=</span>server-cert.pem</span>
<span class="token constant">ssl_key</span><span class="token attr-value"><span class="token punctuation">=</span>server-key.pem</span></code></pre>
   </div>
   <p>
    To specify in addition that clients are required to use
        encrypted connections, enable the
    <a class="link" href="server-system-variables.html#sysvar_require_secure_transport">
     <code class="literal">
      require_secure_transport
     </code>
    </a>
    system
        variable:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa65214602"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">ssl_ca</span><span class="token attr-value"><span class="token punctuation">=</span>ca.pem</span>
<span class="token constant">ssl_cert</span><span class="token attr-value"><span class="token punctuation">=</span>server-cert.pem</span>
<span class="token constant">ssl_key</span><span class="token attr-value"><span class="token punctuation">=</span>server-key.pem</span>
<span class="token constant">require_secure_transport</span><span class="token attr-value"><span class="token punctuation">=</span>ON</span></code></pre>
   </div>
   <p>
    Each certificate and key system variable names a file in PEM
        format. Should you need to create the required certificate and
        key files, see
    <a class="xref" href="creating-ssl-rsa-files.html" title="8.3.3 Creating SSL and RSA Certificates and Keys">
     Section 8.3.3, “Creating SSL and RSA Certificates and Keys”
    </a>
    . MySQL
        servers compiled using OpenSSL can generate missing certificate
        and key files automatically at startup. See
    <a class="xref" href="creating-ssl-rsa-files-using-mysql.html" title="8.3.3.1 Creating SSL and RSA Certificates and Keys using MySQL">
     Section 8.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”
    </a>
    .
        Alternatively, if you have a MySQL source distribution, you can
        test your setup using the demonstration certificate and key
        files in its
    <code class="filename">
     mysql-test/std_data
    </code>
    directory.
   </p>
   <p>
    The server performs certificate and key file autodiscovery. If
        no explicit encrypted-connection options are given to configure
        encrypted connections, the server attempts to enable
        encrypted-connection support automatically at startup:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If the server discovers valid certificate and key files
            named
       <code class="filename">
        ca.pem
       </code>
       ,
       <code class="filename">
        server-cert.pem
       </code>
       , and
       <code class="filename">
        server-key.pem
       </code>
       in the data directory,
            it enables support for encrypted connections by clients.
            (The files need not have been generated automatically; what
            matters is that they have those names and are valid.)
      </p>
     </li>
     <li class="listitem">
      <p>
       If the server does not find valid certificate and key files
            in the data directory, it continues executing but without
            support for encrypted connections.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the server automatically enables encrypted connection
        support, it writes a note to the error log. If the server
        discovers that the CA certificate is self-signed, it writes a
        warning to the error log. (The certificate is self-signed if
        created automatically by the server.)
   </p>
   <p>
    MySQL also provides these system variables for server-side
        encrypted-connection control:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_ssl_cipher">
        <code class="literal">
         ssl_cipher
        </code>
       </a>
       : The list of
            permissible ciphers for connection encryption.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_ssl_crl">
        <code class="literal">
         ssl_crl
        </code>
       </a>
       : The path name of
            the file containing certificate revocation lists.
            (
       <a class="link" href="server-system-variables.html#sysvar_ssl_crlpath">
        <code class="literal">
         ssl_crlpath
        </code>
       </a>
       is similar but
            specifies the path name of a directory of certificate
            revocation-list files.)
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="server-system-variables.html#sysvar_tls_version">
        <code class="literal">
         tls_version
        </code>
       </a>
       ,
       <a class="link" href="server-system-variables.html#sysvar_tls_ciphersuites">
        <code class="literal">
         tls_ciphersuites
        </code>
       </a>
       : Which
            encryption protocols and ciphersuites the server permits for
            encrypted connections; see
       <a class="xref" href="encrypted-connection-protocols-ciphers.html" title="8.3.2 Encrypted Connection TLS Protocols and Ciphers">
        Section 8.3.2, “Encrypted Connection TLS Protocols and Ciphers”
       </a>
       .
            For example, you can configure
       <a class="link" href="server-system-variables.html#sysvar_tls_version">
        <code class="literal">
         tls_version
        </code>
       </a>
       to prevent
            clients from using less-secure protocols.
      </p>
     </li>
    </ul>
   </div>
   <p>
    If the server cannot create a valid TLS context from the system
        variables for server-side encrypted-connection control, the
        server executes without support for encrypted connections.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="using-encrypted-connections-server-side-runtime-configuration">
       </a>
       Server-Side Runtime Configuration and Monitoring for Encrypted
Connections
      </h4>
     </div>
    </div>
   </div>
   <p>
    The
    <code class="literal">
     tls_
     <em class="replaceable">
      <code>
       xxx
      </code>
     </em>
    </code>
    and
    <code class="literal">
     ssl_
     <em class="replaceable">
      <code>
       xxx
      </code>
     </em>
    </code>
    system
        variables are dynamic and can be set at runtime, not just at
        startup. If changed with
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
        GLOBAL
     </code>
    </a>
    , the new values apply only until server
        restart. If changed with
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
        PERSIST
     </code>
    </a>
    , the new values also carry over to subsequent
        server restarts. See
    <a class="xref" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     Section 15.7.6.1, “SET Syntax for Variable Assignment”
    </a>
    . However,
        runtime changes to these variables do not immediately affect the
        TLS context for new connections, as explained later in this
        section.
   </p>
   <p>
    Along with the change that enables runtime changes to the TLS
        context-related system variables, the server enables runtime
        updates to the actual TLS context used for new connections. This
        capability may be useful, for example, to avoid restarting a
        MySQL server that has been running so long that its SSL
        certificate has expired.
   </p>
   <p>
    To create the initial TLS context, the server uses the values
        that the context-related system variables have at startup. To
        expose the context values, the server also initializes a set of
        corresponding status variables. The following table shows the
        system variables that define the TLS context and the
        corresponding status variables that expose the currently active
        context values.
   </p>
   <div class="table">
    <a name="tls-context-variables-table">
    </a>
    <p class="title">
     <b>
      Table 8.12 System and Status Variables for Server Main Connection Interface TLS Context
     </b>
    </p>
    <div class="table-contents">
     <table summary="The system variables that define the server TLS context and the corresponding status variables that expose active context values.">
      <colgroup>
       <col style="width: 45%"/>
       <col style="width: 55%"/>
      </colgroup>
      <thead>
       <tr>
        <th>
         System Variable Name
        </th>
        <th>
         Corresponding Status Variable Name
        </th>
       </tr>
      </thead>
      <tbody>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_ca">
          <code class="literal">
           ssl_ca
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_ca">
          <code class="literal">
           Current_tls_ca
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_capath">
          <code class="literal">
           ssl_capath
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_capath">
          <code class="literal">
           Current_tls_capath
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
          <code class="literal">
           ssl_cert
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_cert">
          <code class="literal">
           Current_tls_cert
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_cipher">
          <code class="literal">
           ssl_cipher
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_cipher">
          <code class="literal">
           Current_tls_cipher
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_crl">
          <code class="literal">
           ssl_crl
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_crl">
          <code class="literal">
           Current_tls_crl
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_crlpath">
          <code class="literal">
           ssl_crlpath
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_crlpath">
          <code class="literal">
           Current_tls_crlpath
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_ssl_key">
          <code class="literal">
           ssl_key
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_key">
          <code class="literal">
           Current_tls_key
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_tls_ciphersuites">
          <code class="literal">
           tls_ciphersuites
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_ciphersuites">
          <code class="literal">
           Current_tls_ciphersuites
          </code>
         </a>
        </td>
       </tr>
       <tr>
        <td>
         <a class="link" href="server-system-variables.html#sysvar_tls_version">
          <code class="literal">
           tls_version
          </code>
         </a>
        </td>
        <td>
         <a class="link" href="server-status-variables.html#statvar_Current_tls_version">
          <code class="literal">
           Current_tls_version
          </code>
         </a>
        </td>
       </tr>
      </tbody>
     </table>
    </div>
   </div>
   <br class="table-break"/>
   <p>
    Those active TLS context values are also exposed as properties
        in the Performance Schema
    <a class="link" href="performance-schema-tls-channel-status-table.html" title="29.12.22.9 The tls_channel_status Table">
     <code class="literal">
      tls_channel_status
     </code>
    </a>
    table, along
        with the properties for any other active TLS contexts.
   </p>
   <p>
    To reconfigure the TLS context at runtime, use this procedure:
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       Set each TLS context-related system variable that should be
            changed to its new value.
      </p>
     </li>
     <li class="listitem">
      <p>
       Execute
       <a class="link" href="alter-instance.html#alter-instance-reload-tls">
        <code class="literal">
         ALTER INSTANCE RELOAD
            TLS
        </code>
       </a>
       . This statement reconfigures the active TLS
            context from the current values of the TLS context-related
            system variables. It also sets the context-related status
            variables to reflect the new active context values. The
            statement requires the
       <a class="link" href="privileges-provided.html#priv_connection-admin">
        <code class="literal">
         CONNECTION_ADMIN
        </code>
       </a>
       privilege.
      </p>
     </li>
     <li class="listitem">
      <p>
       New connections established after execution of
       <a class="link" href="alter-instance.html#alter-instance-reload-tls">
        <code class="literal">
         ALTER INSTANCE RELOAD TLS
        </code>
       </a>
       use
            the new TLS context. Existing connections remain unaffected.
            If existing connections should be terminated, use the
       <a class="link" href="kill.html" title="15.7.8.4 KILL Statement">
        <code class="literal">
         KILL
        </code>
       </a>
       statement.
      </p>
     </li>
    </ol>
   </div>
   <p>
    The members of each pair of system and status variables may have
        different values temporarily due to the way the reconfiguration
        procedure works:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Changes to the system variables prior to
       <a class="link" href="alter-instance.html#alter-instance-reload-tls">
        <code class="literal">
         ALTER INSTANCE RELOAD TLS
        </code>
       </a>
       do
            not change the TLS context. At this point, those changes
            have no effect on new connections, and corresponding
            context-related system and status variables may have
            different values. This enables you to make any changes
            required to individual system variables, then update the
            active TLS context atomically with
       <a class="link" href="alter-instance.html#alter-instance-reload-tls">
        <code class="literal">
         ALTER INSTANCE RELOAD TLS
        </code>
       </a>
       after all system variable changes have been made.
      </p>
     </li>
     <li class="listitem">
      <p>
       After
       <a class="link" href="alter-instance.html#alter-instance-reload-tls">
        <code class="literal">
         ALTER INSTANCE RELOAD
            TLS
        </code>
       </a>
       , corresponding system and status variables
            have the same values. This remains true until the next
            change to the system variables.
      </p>
     </li>
    </ul>
   </div>
   <p>
    In some cases,
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER INSTANCE RELOAD
        TLS
     </code>
    </a>
    by itself may suffice to reconfigure the TLS
        context, without changing any system variables. Suppose that the
        certificate in the file named by
    <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
     <code class="literal">
      ssl_cert
     </code>
    </a>
    has expired. It is
        sufficient to replace the existing file contents with a
        nonexpired certificate and execute
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER
        INSTANCE RELOAD TLS
     </code>
    </a>
    to cause the new file contents to
        be read and used for new connections.
   </p>
   <p>
    The server implements independent connection-encryption
        configuration for the administrative connection interface. See
    <a class="xref" href="administrative-connection-interface.html#administrative-interface-encrypted-connections" title="Administrative Interface Support for Encrypted Connections">
     Administrative Interface Support for Encrypted Connections
    </a>
    .
        In addition,
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER INSTANCE RELOAD
        TLS
     </code>
    </a>
    is extended with a
    <code class="literal">
     FOR CHANNEL
    </code>
    clause that enables specifying the channel (interface) for which
        to reload the TLS context. See
    <a class="xref" href="alter-instance.html" title="15.1.5 ALTER INSTANCE Statement">
     Section 15.1.5, “ALTER INSTANCE Statement”
    </a>
    .
        There are no status variables to expose the administrative
        interface TLS context, but the Performance Schema
    <a class="link" href="performance-schema-tls-channel-status-table.html" title="29.12.22.9 The tls_channel_status Table">
     <code class="literal">
      tls_channel_status
     </code>
    </a>
    table exposes
        TLS properties for both the main and administrative interfaces.
        See
    <a class="xref" href="performance-schema-tls-channel-status-table.html" title="29.12.22.9 The tls_channel_status Table">
     Section 29.12.22.9, “The tls_channel_status Table”
    </a>
    .
   </p>
   <p>
    Updating the main interface TLS context has these effects:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       The update changes the TLS context used for new connections
            on the main connection interface.
      </p>
     </li>
     <li class="listitem">
      <p>
       The update also changes the TLS context used for new
            connections on the administrative interface unless some
            nondefault TLS parameter value is configured for that
            interface.
      </p>
     </li>
     <li class="listitem">
      <p>
       The update does not affect the TLS context used by other
            enabled server plugins or components such as Group
            Replication or X Plugin:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          To apply the main interface reconfiguration to Group
                Replication's group communication connections, which
                take their settings from the server's TLS
                context-related system variables, you must execute
          <a class="link" href="stop-group-replication.html" title="15.4.3.2 STOP GROUP_REPLICATION Statement">
           <code class="literal">
            STOP GROUP_REPLICATION
           </code>
          </a>
          followed by
          <a class="link" href="start-group-replication.html" title="15.4.3.1 START GROUP_REPLICATION Statement">
           <code class="literal">
            START
                GROUP_REPLICATION
           </code>
          </a>
          to stop and restart Group
                Replication.
         </p>
        </li>
        <li class="listitem">
         <p>
          X Plugin initializes its TLS context at plugin
                initialization as described at
          <a class="xref" href="x-plugin-encrypted-connections.html" title="22.5.3 Using Encrypted Connections with X Plugin">
           Section 22.5.3, “Using Encrypted Connections with X Plugin”
          </a>
          . This
                context does not change thereafter.
         </p>
        </li>
       </ul>
      </div>
     </li>
    </ul>
   </div>
   <p>
    By default, the
    <code class="literal">
     RELOAD TLS
    </code>
    action rolls back
        with an error and has no effect if the configuration values do
        not permit creation of the new TLS context. The previous context
        values continue to be used for new connections. If the optional
    <code class="literal">
     NO ROLLBACK ON ERROR
    </code>
    clause is given and the
        new context cannot be created, rollback does not occur. Instead,
        a warning is generated and encryption is disabled for new
        connections on the interface to which the statement applies.
   </p>
   <p>
    Options that enable or disable encrypted connections on a
        connection interface have an effect only at startup. For
        example, the
    <a class="link" href="server-system-variables.html#sysvar_tls_version">
     <code class="option">
      --tls-version
     </code>
    </a>
    and
    <a class="link" href="server-system-variables.html#sysvar_admin_tls_version">
     <code class="option">
      --admin-tls-version
     </code>
    </a>
    options
        affect only at startup whether the main and administrative
        interfaces support those TLS versions. Such options are ignored
        and have no effect on the operation of
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER INSTANCE RELOAD TLS
     </code>
    </a>
    at
        runtime. For example, you can set
    <a class="link" href="server-system-variables.html#sysvar_tls_version">
     <code class="option">
      tls_version=''
     </code>
    </a>
    to start the
        server with encrypted connections disabled on the main
        interface, then reconfigure TLS and execute
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER INSTANCE RELOAD TLS
     </code>
    </a>
    to
        enable encrypted connections at runtime.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="using-encrypted-connections-client-side-configuration">
       </a>
       Client-Side Configuration for Encrypted Connections
      </h4>
     </div>
    </div>
   </div>
   <p>
    For a complete list of client options related to establishment
        of encrypted connections, see
    <a class="xref" href="connection-options.html#encrypted-connection-options" title="Command Options for Encrypted Connections">
     Command Options for Encrypted Connections
    </a>
    .
   </p>
   <p>
    By default, MySQL client programs attempt to establish an
        encrypted connection if the server supports encrypted
        connections, with further control available through the
    <a class="link" href="connection-options.html#option_general_ssl-mode">
     <code class="option">
      --ssl-mode
     </code>
    </a>
    option:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       In the absence of an
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode
        </code>
       </a>
       option, clients
            attempt to connect using encryption, falling back to an
            unencrypted connection if an encrypted connection cannot be
            established. This is also the behavior with an explicit
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=PREFERRED
        </code>
       </a>
       option.
      </p>
     </li>
     <li class="listitem">
      <p>
       With
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=REQUIRED
        </code>
       </a>
       ,
            clients require an encrypted connection and fail if one
            cannot be established.
      </p>
     </li>
     <li class="listitem">
      <p>
       With
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=DISABLED
        </code>
       </a>
       ,
            clients use an unencrypted connection.
      </p>
     </li>
     <li class="listitem">
      <p>
       With
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=VERIFY_CA
        </code>
       </a>
       or
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=VERIFY_IDENTITY
        </code>
       </a>
       ,
            clients require an encrypted connection, and also perform
            verification against the server CA certificate and (with
       <code class="literal">
        VERIFY_IDENTITY
       </code>
       ) against the server host
            name in its certificate.
      </p>
     </li>
    </ul>
   </div>
   <div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Important
    </div>
    <p>
     The default setting,
     <a class="link" href="connection-options.html#option_general_ssl-mode">
      <code class="option">
       --ssl-mode=PREFERRED
      </code>
     </a>
     , produces
          an encrypted connection if the other default settings are
          unchanged. However, to help prevent sophisticated
          man-in-the-middle attacks, it is important for the client to
          verify the server’s identity. The settings
     <a class="link" href="connection-options.html#option_general_ssl-mode">
      <code class="option">
       --ssl-mode=VERIFY_CA
      </code>
     </a>
     and
     <a class="link" href="connection-options.html#option_general_ssl-mode">
      <code class="option">
       --ssl-mode=VERIFY_IDENTITY
      </code>
     </a>
     are a better choice than the default setting to help prevent
          this type of attack.
     <code class="literal">
      VERIFY_CA
     </code>
     makes the
          client check that the server’s certificate is valid.
     <code class="literal">
      VERIFY_IDENTITY
     </code>
     makes the client check that
          the server’s certificate is valid, and also makes the client
          check that the host name the client is using matches the
          identity in the server’s certificate. To implement one of
          these settings, you must first ensure that the CA certificate
          for the server is reliably available to all the clients that
          use it in your environment, otherwise availability issues will
          result. For this reason, they are not the default setting.
    </p>
   </div>
   <p>
    Attempts to establish an unencrypted connection fail if the
    <a class="link" href="server-system-variables.html#sysvar_require_secure_transport">
     <code class="literal">
      require_secure_transport
     </code>
    </a>
    system
        variable is enabled on the server side to cause the server to
        require encrypted connections. See
    <a class="xref" href="using-encrypted-connections.html#mandatory-encrypted-connections" title="Configuring Encrypted Connections as Mandatory">
     Configuring Encrypted Connections as Mandatory
    </a>
    .
   </p>
   <p>
    The following options on the client side identify the
        certificate and key files clients use when establishing
        encrypted connections to the server. They are similar to the
    <a class="link" href="server-system-variables.html#sysvar_ssl_ca">
     <code class="literal">
      ssl_ca
     </code>
    </a>
    ,
    <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
     <code class="literal">
      ssl_cert
     </code>
    </a>
    , and
    <a class="link" href="server-system-variables.html#sysvar_ssl_key">
     <code class="literal">
      ssl_key
     </code>
    </a>
    system variables used
        on the server side, but
    <a class="link" href="connection-options.html#option_general_ssl-cert">
     <code class="option">
      --ssl-cert
     </code>
    </a>
    and
    <a class="link" href="connection-options.html#option_general_ssl-key">
     <code class="option">
      --ssl-key
     </code>
    </a>
    identify the client
        public and private key:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_ssl-ca">
        <code class="option">
         --ssl-ca
        </code>
       </a>
       : The path name of
            the Certificate Authority (CA) certificate file. This
            option, if used, must specify the same certificate used by
            the server. (
       <code class="option">
        --ssl-capath
       </code>
       is similar but
            specifies the path name of a directory of CA certificate
            files.)
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_ssl-cert">
        <code class="option">
         --ssl-cert
        </code>
       </a>
       : The path name of
            the client public key certificate file.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_ssl-key">
        <code class="option">
         --ssl-key
        </code>
       </a>
       : The path name of
            the client private key file.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For additional security relative to that provided by the default
        encryption, clients can supply a CA certificate matching the one
        used by the server and enable host name identity verification.
        In this way, the server and client place their trust in the same
        CA certificate and the client verifies that the host to which it
        connected is the one intended:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       To specify the CA certificate, use
       <a class="link" href="connection-options.html#option_general_ssl-ca">
        <code class="option">
         --ssl-ca
        </code>
       </a>
       (or
       <a class="link" href="connection-options.html#option_general_ssl-capath">
        <code class="option">
         --ssl-capath
        </code>
       </a>
       ), and specify
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=VERIFY_CA
        </code>
       </a>
       .
      </p>
     </li>
     <li class="listitem">
      <p>
       To enable host name identity verification as well, use
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=VERIFY_IDENTITY
        </code>
       </a>
       rather than
       <a class="link" href="connection-options.html#option_general_ssl-mode">
        <code class="option">
         --ssl-mode=VERIFY_CA
        </code>
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
   <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Note
    </div>
    <p>
     Host name identity verification with
     <code class="literal">
      VERIFY_IDENTITY
     </code>
     does not work with
          self-signed certificates that are created automatically by the
          server (see
     <a class="xref" href="creating-ssl-rsa-files-using-mysql.html" title="8.3.3.1 Creating SSL and RSA Certificates and Keys using MySQL">
      Section 8.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”
     </a>
     ). Such
          self-signed certificates do not contain the server name as the
          Common Name value.
    </p>
   </div>
   <p>
    MySQL also provides these options for client-side
        encrypted-connection control:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_ssl-cipher">
        <code class="option">
         --ssl-cipher
        </code>
       </a>
       : The list of
            permissible ciphers for connection encryption.
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_ssl-crl">
        <code class="option">
         --ssl-crl
        </code>
       </a>
       : The path name of
            the file containing certificate revocation lists.
            (
       <code class="option">
        --ssl-crlpath
       </code>
       is similar but specifies the
            path name of a directory of certificate revocation-list
            files.)
      </p>
     </li>
     <li class="listitem">
      <p>
       <a class="link" href="connection-options.html#option_general_tls-version">
        <code class="option">
         --tls-version
        </code>
       </a>
       ,
       <a class="link" href="connection-options.html#option_general_tls-ciphersuites">
        <code class="option">
         --tls-ciphersuites
        </code>
       </a>
       : The
            permitted encryption protocols and ciphersuites; see
       <a class="xref" href="encrypted-connection-protocols-ciphers.html" title="8.3.2 Encrypted Connection TLS Protocols and Ciphers">
        Section 8.3.2, “Encrypted Connection TLS Protocols and Ciphers”
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
   <p>
    Depending on the encryption requirements of the MySQL account
        used by a client, the client may be required to specify certain
        options to connect using encryption to the MySQL server.
   </p>
   <p>
    Suppose that you want to connect using an account that has no
        special encryption requirements or that was created using a
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement that
        included the
    <code class="literal">
     REQUIRE SSL
    </code>
    clause. Assuming
        that the server supports encrypted connections, a client can
        connect using encryption with no
    <a class="link" href="connection-options.html#option_general_ssl-mode">
     <code class="option">
      --ssl-mode
     </code>
    </a>
    option or with an
        explicit
    <a class="link" href="connection-options.html#option_general_ssl-mode">
     <code class="option">
      --ssl-mode=PREFERRED
     </code>
    </a>
    option:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa50975263"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql</code></pre>
   </div>
   <p>
    Or:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa46147351"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>PREFERRED</span></code></pre>
   </div>
   <p>
    For an account created with a
    <code class="literal">
     REQUIRE SSL
    </code>
    clause, the connection attempt fails if an encrypted connection
        cannot be established. For an account with no special encryption
        requirements, the attempt falls back to an unencrypted
        connection if an encrypted connection cannot be established. To
        prevent fallback and fail if an encrypted connection cannot be
        obtained, connect like this:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa75723591"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>REQUIRED</span></code></pre>
   </div>
   <p>
    If the account has more stringent security requirements, other
        options must be specified to establish an encrypted connection:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       For accounts created with a
       <code class="literal">
        REQUIRE X509
       </code>
       clause, clients must specify at least
       <a class="link" href="connection-options.html#option_general_ssl-cert">
        <code class="option">
         --ssl-cert
        </code>
       </a>
       and
       <a class="link" href="connection-options.html#option_general_ssl-key">
        <code class="option">
         --ssl-key
        </code>
       </a>
       . In addition,
       <a class="link" href="connection-options.html#option_general_ssl-ca">
        <code class="option">
         --ssl-ca
        </code>
       </a>
       (or
       <a class="link" href="connection-options.html#option_general_ssl-capath">
        <code class="option">
         --ssl-capath
        </code>
       </a>
       ) is recommended
            so that the public certificate provided by the server can be
            verified. For example (enter the command on a single line):
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa35146522"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--ssl-ca</span><span class="token attr-value"><span class="token punctuation">=</span>ca.pem</span>
      <span class="token constant">--ssl-cert</span><span class="token attr-value"><span class="token punctuation">=</span>client-cert.pem</span>
      <span class="token constant">--ssl-key</span><span class="token attr-value"><span class="token punctuation">=</span>client-key.pem</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       For accounts created with a
       <code class="literal">
        REQUIRE
            ISSUER
       </code>
       or
       <code class="literal">
        REQUIRE SUBJECT
       </code>
       clause, the encryption requirements are the same as for
       <code class="literal">
        REQUIRE X509
       </code>
       , but the certificate must
            match the issue or subject, respectively, specified in the
            account definition.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For additional information about the
    <code class="literal">
     REQUIRE
    </code>
    clause, see
    <a class="xref" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     Section 15.7.1.3, “CREATE USER Statement”
    </a>
    .
   </p>
   <p>
    MySQL servers can generate client certificate and key files that
        clients can use to connect to MySQL server instances. See
    <a class="xref" href="creating-ssl-rsa-files.html" title="8.3.3 Creating SSL and RSA Certificates and Keys">
     Section 8.3.3, “Creating SSL and RSA Certificates and Keys”
    </a>
    .
   </p>
   <div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
    <div class="admon-title">
     Important
    </div>
    <p>
     If a client connecting to a MySQL server instance uses an SSL
          certificate with the
     <code class="literal">
      extendedKeyUsage
     </code>
     extension (an X.509 v3 extension), the extended key usage must
          include client authentication (
     <code class="literal">
      clientAuth
     </code>
     ).
          If the SSL certificate is only specified for server
          authentication (
     <code class="literal">
      serverAuth
     </code>
     ) and other
          non-client certificate purposes, certificate verification
          fails and the client connection to the MySQL server instance
          fails. There is no
     <code class="literal">
      extendedKeyUsage
     </code>
     extension in SSL certificates generated by MySQL Server (as
          described in
     <a class="xref" href="creating-ssl-rsa-files-using-mysql.html" title="8.3.3.1 Creating SSL and RSA Certificates and Keys using MySQL">
      Section 8.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”
     </a>
     ),
          and SSL certificates created using the
     <span class="command">
      <strong>
       openssl
      </strong>
     </span>
     command following the instructions
          in
     <a class="xref" href="creating-ssl-files-using-openssl.html" title="8.3.3.2 Creating SSL Certificates and Keys Using openssl">
      Section 8.3.3.2, “Creating SSL Certificates and Keys Using openssl”
     </a>
     . If you
          use your own client certificate created in another way, ensure
          any
     <code class="literal">
      extendedKeyUsage
     </code>
     extension includes
          client authentication.
    </p>
   </div>
   <p>
    To prevent use of encryption and override other
    <code class="option">
     --ssl-
     <em class="replaceable">
      <code>
       xxx
      </code>
     </em>
    </code>
    options,
        invoke the client program with
    <a class="link" href="connection-options.html#option_general_ssl-mode">
     <code class="option">
      --ssl-mode=DISABLED
     </code>
    </a>
    :
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa29124270"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>DISABLED</span></code></pre>
   </div>
   <p>
    To determine whether the current connection with the server uses
        encryption, check the session value of the
    <a class="link" href="server-status-variables.html#statvar_Ssl_cipher">
     <code class="literal">
      Ssl_cipher
     </code>
    </a>
    status variable. If
        the value is empty, the connection is not encrypted. Otherwise,
        the connection is encrypted and the value indicates the
        encryption cipher. For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa55006083"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SHOW</span> <span class="token keyword">SESSION</span> <span class="token keyword">STATUS</span> <span class="token operator">LIKE</span> <span class="token string">'Ssl_cipher'</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> Variable_name <span class="token punctuation">|</span> Value                     <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> Ssl_cipher    <span class="token punctuation">|</span> DHE<span class="token punctuation">-</span>RSA<span class="token punctuation">-</span>AES128<span class="token punctuation">-</span>GCM<span class="token punctuation">-</span>SHA256 <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
   </div>
   <p>
    For the
    <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
     <span class="command">
      <strong>
       mysql
      </strong>
     </span>
    </a>
    client, an alternative is to
        use the
    <code class="literal">
     STATUS
    </code>
    or
    <code class="literal">
     \s
    </code>
    command and check the
    <code class="literal">
     SSL
    </code>
    line:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa13798224"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> \s
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
<span class="token keyword">SSL</span>: <span class="token operator">Not</span> <span class="token keyword">in</span> <span class="token keyword">use</span>
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span></code></pre>
   </div>
   <p>
    Or:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa13118727"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> \s
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
<span class="token keyword">SSL</span>: <span class="token keyword">Cipher</span> <span class="token keyword">in</span> <span class="token keyword">use</span> <span class="token operator">is</span> DHE<span class="token operator">-</span>RSA<span class="token operator">-</span>AES128<span class="token operator">-</span>GCM<span class="token operator">-</span>SHA256
<span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span></code></pre>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="enforce-certificate-validation">
       </a>
       Configuring Certificate Validation Enforcement
      </h4>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045246918224">
   </a>
   <p>
    The
    <a class="link" href="server-system-variables.html#sysvar_tls_certificates_enforced_validation">
     <code class="option">
      --tls-certificates-enforced-validation
     </code>
    </a>
    option enables validation of the server public key certificate
        file, Certificate Authority (CA) certificate files, and
        certificate revocation-list files at server startup:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-terminal"><div class="docs-select-all right" id="sa51108319"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysqld <span class="token property">--tls-certificates-enforced-validation</span></code></pre>
   </div>
   <p>
    If set to
    <code class="literal">
     ON
    </code>
    , the server stops execution of
        the startup in case of invalid certificates. The server informs
        DBAs by providing valid debug messages, error messages, or both
        depending on the status of the certificates. This capability may
        be useful, for example, to avoid restarting a MySQL server that
        has been running so long that its SSL certificate has expired.
   </p>
   <p>
    Similarly, when you execute the
    <a class="link" href="alter-instance.html#alter-instance-reload-tls">
     <code class="literal">
      ALTER
        INSTANCE RELOAD TLS
     </code>
    </a>
    statement to change the TLS
        context at runtime, the new server and CA certificate files are
        not used if validation fails. The server continues to use the
        old certificates in this case. For more information about
        changing the TLS context dynamically, see
    <a class="xref" href="using-encrypted-connections.html#using-encrypted-connections-server-side-runtime-configuration" title="Server-Side Runtime Configuration and Monitoring for Encrypted Connections">
     Server-Side Runtime Configuration and Monitoring for Encrypted
        Connections
    </a>
    .
   </p>
   <p>
    <span class="strong">
     <strong>
      Validating CA Certificates
     </strong>
    </span>
   </p>
   <p>
    For a connection using the server main interface:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_ssl_ca">
        <code class="option">
         --ssl_ca
        </code>
       </a>
       is specified,
            then the server validates the respective CA certificate and
            gives the DBA an appropriate warning message.
      </p>
     </li>
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_ssl_capath">
        <code class="option">
         --ssl_capath
        </code>
       </a>
       is specified,
            then the server validates all the CA certificates in the
            respective folder and gives the DBA an appropriate warning
            message.
      </p>
     </li>
     <li class="listitem">
      <p>
       If SSL parameters are not specified, by default the server
            validates the CA certificate present in the data directory
            and gives the DBA an appropriate warning message.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For a connection using the server administrative interface:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_admin_ssl_ca">
        <code class="option">
         --admin_ssl_ca
        </code>
       </a>
       is
            specified, then the server validates the respective CA
            certificate and gives the DBA an appropriate warning
            message.
      </p>
     </li>
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_admin_ssl_capath">
        <code class="option">
         --admin_ssl_capath
        </code>
       </a>
       is
            specified, then the server validates all of the CA
            certificates in the respective folder and gives the DBA an
            appropriate warning message.
      </p>
     </li>
     <li class="listitem">
      <p>
       If administrative SSL parameters are not specified, by
            default the server validates the CA certificate present in
            the data directory and gives the DBA an appropriate warning
            message.
      </p>
     </li>
    </ul>
   </div>
   <p>
    <span class="strong">
     <strong>
      Validating the Server
        Certificate
     </strong>
    </span>
   </p>
   <p>
    For a connection using the server main interface:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
        <code class="option">
         --ssl_cert
        </code>
       </a>
       is not
            specified, then the server validates the server certificate
            in default data directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_ssl_cert">
        <code class="option">
         --ssl_cert
        </code>
       </a>
       is given, then
            the server validates the server certificate, taking into
            consideration
       <a class="link" href="server-system-variables.html#sysvar_ssl_crl">
        <code class="option">
         --ssl_crl
        </code>
       </a>
       , if
            specified.
      </p>
     </li>
     <li class="listitem">
      <p>
       If a DBA sets the command-line option to validate
            certificates, then the server stops in case of invalid
            certificates and an appropriate error message is displayed
            to the DBA. Otherwise, the server emits warning messages to
            the DBA and the server starts.
      </p>
     </li>
    </ul>
   </div>
   <p>
    For a connection using the server administrative interface:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_admin_ssl_cert">
        <code class="option">
         --admin_ssl_cert
        </code>
       </a>
       is not
            specified, then the server validates the server certificate
            in default data directory.
      </p>
     </li>
     <li class="listitem">
      <p>
       If
       <a class="link" href="server-system-variables.html#sysvar_admin_ssl_cert">
        <code class="option">
         --admin_ssl_cert
        </code>
       </a>
       is given,
            then the server validates the server certificate, taking
            into consideration
       <a class="link" href="server-system-variables.html#sysvar_admin_ssl_crl">
        <code class="option">
         --admin_ssl_crl
        </code>
       </a>
       , if
            specified.
      </p>
     </li>
     <li class="listitem">
      <p>
       If a DBA sets the command-line option to validate
            certificates, then the server stops in case of invalid
            certificates and an appropriate error message is displayed
            to the DBA. Otherwise, the server emits warning messages to
            the DBA and the server starts.
      </p>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="mandatory-encrypted-connections">
       </a>
       Configuring Encrypted Connections as Mandatory
      </h4>
     </div>
    </div>
   </div>
   <a class="indexterm" name="idm46045246881056">
   </a>
   <p>
    For some MySQL deployments it may be not only desirable but
        mandatory to use encrypted connections (for example, to satisfy
        regulatory requirements). This section discusses configuration
        settings that enable you to do this. These levels of control are
        available:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       You can configure the server to require that clients connect
            using encrypted connections.
      </p>
     </li>
     <li class="listitem">
      <p>
       You can invoke individual client programs to require an
            encrypted connection, even if the server permits but does
            not require encryption.
      </p>
     </li>
     <li class="listitem">
      <p>
       You can configure individual MySQL accounts to be usable
            only over encrypted connections.
      </p>
     </li>
    </ul>
   </div>
   <p>
    To require that clients connect using encrypted connections,
        enable the
    <a class="link" href="server-system-variables.html#sysvar_require_secure_transport">
     <code class="literal">
      require_secure_transport
     </code>
    </a>
    system
        variable. For example, put these lines in the server
    <code class="filename">
     my.cnf
    </code>
    file:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa7441136"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">require_secure_transport</span><span class="token attr-value"><span class="token punctuation">=</span>ON</span></code></pre>
   </div>
   <p>
    Alternatively, to set and persist the value at runtime, use this
        statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa14199433"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SET</span> <span class="token keyword">PERSIST</span> require_secure_transport<span class="token operator">=</span><span class="token keyword">ON</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     <code class="literal">
      SET
        PERSIST
     </code>
    </a>
    sets a value for the running MySQL instance.
        It also saves the value, causing it to be used for subsequent
        server restarts. See
    <a class="xref" href="set-variable.html" title="15.7.6.1 SET Syntax for Variable Assignment">
     Section 15.7.6.1, “SET Syntax for Variable Assignment”
    </a>
    .
   </p>
   <p>
    With
    <a class="link" href="server-system-variables.html#sysvar_require_secure_transport">
     <code class="literal">
      require_secure_transport
     </code>
    </a>
    enabled, client connections to the server are required to use
        some form of secure transport, and the server permits only
        TCP/IP connections that use SSL, or connections that use a
        socket file (on Unix) or shared memory (on Windows). The server
        rejects nonsecure connection attempts, which fail with an
    <a class="ulink" href="/doc/mysql-errors/8.4/en/server-error-reference.html#error_er_secure_transport_required" target="_top">
     <code class="literal">
      ER_SECURE_TRANSPORT_REQUIRED
     </code>
    </a>
    error.
   </p>
   <p>
    To invoke a client program such that it requires an encrypted
        connection whether or not the server requires encryption, use an
    <a class="link" href="connection-options.html#option_general_ssl-mode">
     <code class="option">
      --ssl-mode
     </code>
    </a>
    option value of
    <code class="literal">
     REQUIRED
    </code>
    ,
    <code class="literal">
     VERIFY_CA
    </code>
    , or
    <code class="literal">
     VERIFY_IDENTITY
    </code>
    . For example:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa72016127"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal">mysql <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>REQUIRED</span>
mysqldump <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>VERIFY_CA</span>
mysqladmin <span class="token constant">--ssl-mode</span><span class="token attr-value"><span class="token punctuation">=</span>VERIFY_IDENTITY</span></code></pre>
   </div>
   <p>
    To configure a MySQL account to be usable only over encrypted
        connections, include a
    <code class="literal">
     REQUIRE
    </code>
    clause in the
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    statement that
        creates the account, specifying in that clause the encryption
        characteristics you require. For example, to require an
        encrypted connection and the use of a valid X.509 certificate,
        use
    <code class="literal">
     REQUIRE X509
    </code>
    :
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa95121199"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'jeffrey'</span>@<span class="token string">'localhost'</span> <span class="token keyword">REQUIRE</span> <span class="token keyword">X509</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    For additional information about the
    <code class="literal">
     REQUIRE
    </code>
    clause, see
    <a class="xref" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     Section 15.7.1.3, “CREATE USER Statement”
    </a>
    .
   </p>
   <p>
    To modify existing accounts that have no encryption
        requirements, use the
    <a class="link" href="alter-user.html" title="15.7.1.1 ALTER USER Statement">
     <code class="literal">
      ALTER USER
     </code>
    </a>
    statement.
   </p>
  </div>
 </div>
 <br/>
</div>
