WL#8785: Support multi-state SSL option

Status: Complete   —   Priority: Medium

MySQL historically supports two SSL states in client arguments:  disabled and
preferred (but not required).  There are other SSL states which could be defined
by clients:

* Enabled (if the server demands it)
* Required
* Verify CA (required + server is among trusted)
* Verify Identity (required + specific server)

The existing --ssl option is defined as a boolean system variable, which
supports many syntax variants (e.g., --skip-ssl, --enable-ssl, --ssl=1,
--ssl=OFF, etc.).  Conversion of this option to an enum is complicated by the
many forms legacy usage may take.

The Verify CA and Verify Identity modes are already controlled by other MySQL
client options (--ssl-ca/--ssl-capath and --ssl-verify-server-cert,
respectively).  These could be simplified into a single "SSL Mode" option:

--ssl-mode=[DISABLED | PREFERRED | REQUIRED | VERIFY_CA | VERIFY_IDENTITY]

User Documentation
==================

http://dev.mysql.com/doc/relnotes/mysql/5.7/en/news-5-7-11.html
http://dev.mysql.com/doc/refman/5.7/en/secure-connection-options.html 
(descriptions for --ssl-mode, --ssl, --ssl-verify-server-cert)
http://dev.mysql.com/doc/refman/5.7/en/mysql-options.html (descriptions for 
MYSQL_OPT_SSL_MODE, MYSQL_OPT_SSL_ENFORCE, MYSQL_OPT_SSL_VERIFY_SERVER_CERT)
FR1 :  Deprecate --ssl client option (and related boolean option equivalents).
FR2 :  Deprecate --ssl-verify-server-cert
FR3.1 :  Add --ssl-mode option.
FR3.2 : Supported option values will be:  DISABLED, PREFERRED,
REQUIRED, VERIFY_CA, and VERIFY_IDENTITY.
FR4.1  DISABLED will be functionally equivalent to --skip-ssl today; no
connections established with --ssl-mode=DISABLED will use TLS/SSL.
FR4.2 : PREFERRED will utilize TLS/SSL whenever the server supports it.
FR4.3 : REQUIRED will establish connections only when TLS/SSL is successfully
negotiated.
FR4.4 : VERIFY_CA will behave as REQUIRED, but also verify the server TLS cert
against configured CA certs.  If no valid matching CA certs are found, the
connection is aborted.
FR 4.5 : VERIFY_IDENTITY will behave as VERIFY_CA, but will also validate that
the server certificate matches the hostname to which the connection was
attempted.  This is equivalent to --ssl-verify-server-cert legacy option.
FR 5.1 : Users defining --ssl-ca or --ssl-capath imply --ssl-mode=VERIFY_CA, if
--ssl-mode is not explicitly set otherwise.
FR 5.2 : Users explicitly defining a combination of --ssl-mode other than
VERIFY_CA or VERIFY_IDENTITY with explicit --ssl-ca or --ssl-capath values
should receive a warning that no verification of server certificate will be
done, despite CA cert options defined. 

0. SSL connection matrix will look like:
client:  
  ssl-mode=DISABLED 
  server:
    ssl=0 - non-SSL connection    
    ssl=1 - non-SSL connection
    user REQUIRED - no connection

  ssl-mode=PREFERRED
  server:
    ssl=0 - non-SSL connection
    ssl=1 - SSL connection
    user REQUIRED - SSL connection

  ssl-mode=REQUIRED
  server:
    ssl=0 - no connection
    ssl=1 - SSL connection
    user REQUIRED - SSL connection

  ssl-mode=VERIFY_CA
  server:
    ssl=0 - no connection
    ssl=1 - SSL connection (CA verified, fail otherwise)
    user REQUIRED - the same 

  ssl-mode=VERIFY_IDENTITY
  server:
    ssl=0 - no connection
    ssl=1 - SSL connection (CA and server verified, fail otherwise)
    user REQUIRED - the same

1. Throw warnings for legacy --ssl option:
"WARNING: --ssl is deprecated and will be removed in a future version. Use --
ssl-
mode instead",
and for --verify-server-cert option:
"WARNING: --verify-server-cert is deprecated and will be removed in a future 
version. Use --ssl-mode=VERIFY_IDENTITY instead".
Update options' help strings.

2. Add enum option
--ssl-mode={DISABLED|PREFERRED|REQUIRED|VERIFY_CA|VERIFY_IDENTITY}
Default value is PREFERRED.

3. Set proper SSL connection options depending on --ssl-mode as "Functional 
Requirements" states:
DISABLED - SSL_ENFORCE=FALSE;
PREFERRED - SSL_ENFORCE=FALSE, SSL_KEY, SSL_CERT, SSL_CIPHER, SSL_CRL, 
SSL_CRLPATH;
REQUIRED - the same but SSL_ENFORCE=TRUE;
VERIFY_CA - the same + SSL_CA, SSL_CAPATH;
VERIFY_IDENTITY - the same + SSL_VERIFY_SERVER_CERT;

4. Check if --ssl-mode is set explicitly, don't change it even if
--ssl-ca or --ssl-capath given. Throw a warning in such cases:
"WARNING: no verification of server certificate will be done. Use --ssl-
mode=VERIFY_CA or VERIFY_IDENTITY".

5. Change mysql-test-run to use --ssl-mode option instead of legacy ones.

6. Change all tests using --ssl, --skip-ssl, --verify-server-cert to use proper 
--ssl-mode instead.

7. The changes will affect the following MySQL clients:
mysql, mysqladmin, mysqlbinlog, mysqlcheck, mysqldump, mysqlimport, mysqlshow, 
mysqlpump, mysqlslap, mysqltest, mysql_upgrade.
No changes in the protocol.

8. Introduce mysql_options()'s enum MYSQL_OPT_SSL_MODE=
{DISABLED=0|PREFERRED|REQUIRED|VERIFY_CA|VERIFY_IDENTITY} option.

9. Deprecate mysql_options()'s MYSQL_OPT_SSL_ENFORCE and 
MYSQL_OPT_SSL_VERIFY_SERVER_CERT options.

10. libmysql minor bump.