MySQL Bugs: #86699: SSL documentation is outdated and misleading

Bug #86699	SSL documentation is outdated and misleading
Submitted:	14 Jun 2017 14:32	Modified:	22 Aug 2017 15:27
Reporter:	Tibor Korocz	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.7	OS:	Any
Assigned to:		CPU Architecture:	Any
Tags:	5.7 SSL

Description:
Hi, 

I configured SSL on MySQL 5.7 I added a user with `REQUIRE SSL` and when I tested I realised that I can connect to the server from the client without specifying the client keys and the connection still uses SSL.

That was really surprising I thought I did something wrong I checked everything multiple times I read the manual but I could connect to MySQL without the client keys and I did not understand how. I thought it works similar like the SSH keys with private and public key pairs. 

But it does not. I spend hours to read the manuals but all of them says you have to specify the keys in the client.... until one of my colleague Alexey Poritskiy found this: 

"As of MySQL 5.7.3, a client need specify only the --ssl option to obtain an encrypted connection. The connection attempt fails if an encrypted connection cannot be established. Before MySQL 5.7.3, the client must specify either the --ssl-ca option, or all three of the --ssl-ca, --ssl-key, and --ssl-cert options."

So after 5.7.3 it works like the websites with HTTPS? If yes we need more detailed documentation about this.

And I found that really funny this few lines is in `Create USER` syntax manual: https://dev.mysql.com/doc/refman/5.7/en/create-user.html#create-user-tls

Why there? This should be documented somewhere in here: https://dev.mysql.com/doc/refman/5.7/en/secure-connections.html

How to repeat:
Install latest MySQL 5.7 configure SSL and try to connect without specifying the client keys.

Suggested fix:
Write a detailed documentation how does it work after 5.7.3.

I also tested it with 5.6 clients and if you try to connect with 5.6 client to 5.7 server with SSL you have to specify the client keys on the client side.

Hi,

Thanks for submitting the bug, I do agree documentation can (and should) be a bit better with regards to ssl, especially with this changes in 5.7. 

Documentation team is informed and they will work on it in future.

kind regards
Bogdan

Posted by developer:
 
In addition to
https://dev.mysql.com/doc/refman/5.7/en/create-user.html#create-user-tls
see:

https://dev.mysql.com/doc/refman/5.7/en/secure-connections.html
(and see end for timeline of SSL changes in 5.7)
https://dev.mysql.com/doc/refman/5.7/en/using-secure-connections.html
(particularly the client-side section)
https://dev.mysql.com/doc/refman/5.7/en/secure-connection-options.html#option_general_ssl-...

Most of those sections already mentioned the "connect securely by default" behavior, but that should be more clear now.