/* * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License, version 2.0, * as published by the Free Software Foundation. * * This program is also distributed with certain software (including * but not limited to OpenSSL) that is licensed under separate terms, * as designated in a particular file or component or in included license * documentation. The authors of MySQL hereby grant you an additional * permission to link the program and your derivative works with the * separately licensed software that they have included with MySQL. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License, version 2.0, for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ /** @page mysqlx_protocol_lifecycle Life Cycle Topics in this section: - @ref lifecycle_Connection - @ref lifecycle_Session - @ref lifecycle_Stages_of_Session_Setup - @ref lifecycle_Authentication - @ref lifecycle_Pipelining - @ref lifecycle_Max_Message_Length - @ref lifecycle_Extensions The following list describes some of the terms introduced in this section: @par Transport Transport layer that exchanges data: TCP sockets, Unix Sockets, Named Pipes, TLS, and so on. @par Connection A lower-level connection between two Endpoints. @par Session The session maintains the state. User-Variables, Temporary Tables, and so on. @par Messages @ref mysqlx_protocol_messages "Messages" are exchanged between Endpoints. On a higher level they build a sequence of Messages with a initial and final Message. @par Endpoints A client or a server. Connection {#lifecycle_Connection} ========== A default connection supports: - supports connection capability negotiation via @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " and @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " - must support at least one of the following: - @ref lifecycle_TLS_Extension "TLS Extension" and PLAIN @ref mysqlx_protocol_authentication "Authentication" or - @ref lifecycle_TLS_Extension "TLS Extension" and EXTERNAL @ref mysqlx_protocol_authentication "Authentication" or - MYSQL41 @ref mysqlx_protocol_authentication "Authentication" or another challenge response authentication mechanism Session {#lifecycle_Session} ======= A session owns state like: - current schema - current character set - temporary tables - user variables - open transactions A session is used by the server and the protocol to manage state. Sessions are: - opened with @ref Mysqlx_Session_AuthenticateStart "@c AuthenticateStart " - reset with @ref Mysqlx_Session_Reset "@c Reset " - closed with @ref Mysqlx_Session_Close "@c Close " Closing a session releases all session related data. Stages of Session Setup {#lifecycle_Stages_of_Session_Setup} ======================= After a client connects to the server it: - may ask for the servers capabilities with @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " - may ask the server to use optional protocol features with @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " - MUST authenticate - may send commands @startuml "Stages of Session Setup" == Negotiation == Client -> Server: CapabilitiesGet() Server --> Client: { "tls": 0, ... } Client -> Server: CapabilitiesSet({"tls" : 1}) Server --> Client: Ok == Authentication == Client -> Server: AuthenticateStart(mech="MYSQL41", ...) Server --> Client: AuthenticateContinue(auth_data="...") Client -> Server: AuthenticateContinue(auth_data="...") Server --> Client: AuthenticateOk() == Commands == ... @enduml In the **Negotiation** step the client checks which features the server supports on the protocol side. After a successful finish of the **Authentication** step the previous Session is discarded and a new Session is created. Further **Command** Messages run within a Session. Authentication {#lifecycle_Authentication} ============== @ref mysqlx_protocol_authentication "Authentication" supports several authentication mechanisms that can be discovered with @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet ". ``authentication.mechanisms`` Server-side supported SASL mechanism: - before TLS connection established: ``[]`` - after TLS connection established: ``["EXTERNAL", "PLAIN" ]`` Required mechanisms: - EXTERNAL (X.509 client certificates) RFC; [RFC 4422\#appendix-A](https://tools.ietf.org/html/rfc4422.html#appendix-A) (required) - PLAIN (over SSL) RFC; [RFC 4616](https://tools.ietf.org/html/rfc4616.html) (required) Other known mechanisms: - MYSQL41 (MySQL 4.1 auth mechanism) @startuml Authentication Client -> Server: AuthenticateStart() loop Server --> Client: AuthenticateContinue() Client -> Server: AuthenticateContinue() end alt Server --> Client: Error() else Server --> Client: AuthenticateOk() end @enduml Pipelining {#lifecycle_Pipelining} ========== The messages may be pipelined: - the client may send the messages without waiting for a reply first - the client should only send messages which safely trigger an Error packet For the server it is no difference if the messages from client where sent in a bulk or if the client waited. The network and send/receive buffers of the Operation System will act as queue. @ref mysqlx_protocol_expectations "Expectations" help to control the behavior of following messages if a pipelined message fails. @par Tip For more information, see @ref mysqlx_protocol_implementation "Implementation Notes". Max Message Length {#lifecycle_Max_Message_Length} ================== If the server receives a message that is larger than the current *Max Message Length*, then it **MUST** close the connection. ``message.maxSendLength`` @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " - ``1048576``: current max message length 1Mbyte @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " - ``2097152``: asks to increase the max message length to 2Mbyte ``message.maxReceiveLength`` @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " - ``1048576``: current max receiving message length 1Mbyte @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " - ``2097152``: asks to increase the max receiving message length to 2Mbyte @note As clients and servers may have to buffer the entire message before it can be processed these limits allow protect against excessive resource usage. Extensions {#lifecycle_Extensions} ========== If the result of @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " contains a extension key from the table below it supports the feature. | Name | Extension | |----------|----------------------------------------------| | ``tls`` | @ref lifecycle_TLS_Extension "TLS Extension" | @note More extensions can be added in future iterations as long as they are announced in ``CapabilitiesGet()`` and documented. ## TLS Extension {#lifecycle_TLS_Extension} The client may assume that the server supports a set of features by default and skip the @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " step: - if the TLS extension isn't supported, then the @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " will fail - if it is supported, then it will succeed @code{cucumber} Feature: extensions Scenario: connecting with TLS, fast path Given a client side X.509 certificate is provided with user name "foo" And client certificate is valid When connecting with TLS established Then handshake should be single-step @endcode @startuml "TLS extension" == Negotiation == Client -> Server: CapabilitiesSet({"tls" : 1}) Server --> Client: Ok note over Client, Server: TLS handshake == Authentication == Client -> Server: AuthenticateStart(mech="EXTERNAL") Server --> Client: AuthenticateOk() == Commands == ... @enduml @ref Mysqlx_Connection_CapabilitiesGet "@c CapabilitiesGet " - ``0``: supported, not in use - ``1``: supported, in use @ref Mysqlx_Connection_CapabilitiesSet "@c CapabilitiesSet " - ``1``: switch to TLS connection after server-side Ok If the server doesn't support the capability, then it will return an error. @note Disabling TLS on a connection may not be supported by the server and should result in an error. */