Life Cycle

Topics in this section:

• Connection
• Session
• Stages of Session Setup
• Authentication
• Pipelining
• Max Message Length
• Extensions

The following list describes some of the terms introduced in this section:

Transport

Transport layer that exchanges data: TCP sockets, Unix Sockets, Named Pipes, TLS, and so on.

Connection

A lower-level connection between two Endpoints.

Session

The session maintains the state. User-Variables, Temporary Tables, and so on.

Messages

Messages are exchanged between Endpoints. On a higher level they build a sequence of Messages with a initial and final Message.

Endpoints

A client or a server.

Connection

A default connection supports:

• supports connection capability negotiation via CapabilitiesGet and CapabilitiesSet
• must support at least one of the following:
  • TLS Extension and PLAIN Authentication or
  • TLS Extension and EXTERNAL Authentication or
  • MYSQL41 Authentication or another challenge response authentication mechanism

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 AuthenticateStart
• reset with Reset
• closed with Close

Closing a session releases all session related data.

Stages of Session Setup

After a client connects to the server it:

• may ask for the servers capabilities with CapabilitiesGet
• may ask the server to use optional protocol features with CapabilitiesSet
• MUST authenticate
• may send commands

Stages of Session Setup

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

Authentication supports several authentication mechanisms that can be discovered with 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 (required)
• PLAIN (over SSL) RFC; RFC 4616 (required)

Other known mechanisms:

• MYSQL41 (MySQL 4.1 auth mechanism)

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.

Expectations help to control the behavior of following messages if a pipelined message fails.

Tip

For more information, see Implementation Notes.

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

CapabilitiesGet

• 1048576: current max message length 1Mbyte

CapabilitiesSet

• 2097152: asks to increase the max message length to 2Mbyte

message.maxReceiveLength

CapabilitiesGet

• 1048576: current max receiving message length 1Mbyte

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

If the result of CapabilitiesGet contains a extension key from the table below it supports the feature.

Name	Extension
tls	TLS Extension

Note

More extensions can be added in future iterations as long as they are announced in CapabilitiesGet() and documented.

TLS Extension

The client may assume that the server supports a set of features by default and skip the CapabilitiesGet step:

• if the TLS extension isn't supported, then the CapabilitiesSet will fail
• if it is supported, then it will succeed

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

TLS extension

CapabilitiesGet

• 0: supported, not in use
• 1: supported, in use

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.