Description:
The sections around 15.2, such as https://dev.mysql.com/doc/internals/en/x-protocol-authentication-mysql41-authentication.ht... talk about the authentication flow between client and server.
When looking at the mysql41 authentication I notice that the actual flow is somewhat different to that shown and is:
Client -> Server: AuthenticateStart(mech="MYSQL41")
Server --> Client: AuthenticateContinue(auth_data="98765432100123456789")
Client --> Server: AuthenticateContinue(auth_data="\0myuser\09876543210987654321098765432109876543210\0")
Server --> Client: Notice # extra message ALWAYS arrives prior to the AuthenticateOK
Server --> Client: AuthenticateOk
How to repeat:
.
Suggested fix:
Various things:
* While your documentation of the Notice message does indicate that it can happen at any time we are not reminded of this fact given the "consistent" behaviour I see at the moment.
It would be good to point this out even if you potentially may decide to change the behaviour. It surprises less if someone is attempting to write their own code to implement the protocol.
* I would also "expect" that until the authorisation is confirmed (thus _sent_) sending me a notification about the change in state may be too early. However, there's little documentation which talks about this at the moment, and clarifying why I get the Notice prior to the AuthenticateOk would be useful.
* I initially tried to authenticate with the PLAIN method. I believe this will only work if using TLS. Is that the case? If it's not then it is not secure. If it is this should be mentioned.
* Missing in the documentation are sample test cases for authentication. I see there are test cases in the javascript unit tests but this is not the place to _define_ expected behaviour. It's much better to define the protocol here in the documentation with sample input and output which is "code free" so that anyone implementing the protocol does not need to look at existing code. It also means that should the code change it MUST follow the documentation not the other way around which I think is important. So please describe the authentication methods and how to "achieve them" here in the documentation with sample test input and output for any of the stages required.
* EXTERNAL documentation is not described. How do this work? Where is it used? Why is it used? How does it compare to other authentication methods?
I notice that AuthenticateOk retuns some AuthData. What is this data?
Basically https://dev.mysql.com/doc/internals/en/x-protocol-authentication-authentication.html and the sections "below it" provide no context, no description of each of the stages in authentication.
If I identify myself incorrectly I seem to get back an Error message. What possible responses should I expect from this?
Summarising. I understand this is the first version of the documentation. It gives me a good start at writing code to talk the X protocol to MySQL. Yet enriching this documentation with more comments and examples will make it much easier to follow and much easier for testers to see if they are doing the right thing and thus get to a working product.
