Connection is done by many exchanges:

  • (Create socket)
  • If first byte from server is 0xFF:
  • else

Initial Handshake Packet

  • int<1> protocol version
  • string<NUL> server version (MariaDB server version for 10.X versions is by default prefixed by "5.5.5-". MariaDB 11.0 and later versions do not have a "5.5.5-" default prefix)
  • int<4> connection id
  • string<8> scramble 1st part (authentication seed)
  • string<1> reserved byte
  • int<2> server capabilities (1st part)
  • int<1> server default collation
  • int<2> status flags
  • int<2> server capabilities (2nd part)
  • if (server_capabilities & PLUGIN_AUTH)
  • else
  • string<6> filler
  • if (server_capabilities & CLIENT_MYSQL)
  • else
  • if (server_capabilities & CLIENT_SECURE_CONNECTION)
    • string<n> scramble 2nd part . Length = max(12, plugin data length - 9)
    • string<1> reserved byte
  • if (server_capabilities & PLUGIN_AUTH)

Client Handshake Response

If the client requests a TLS/SSL connection, first response will be an SSL connection request packet, then a handshake response packet. If no TLS is required, client send directly a handshake response packet.

SSLRequest Packet

  • int<4> client capabilities
  • int<4> max packet size
  • int<1> client's default character set and collation
  • string<19> reserved
  • if not (server_capabilities & CLIENT_MYSQL)
    • int<4> extended client capabilities
  • else


Automatic Encrypted Connections (MariaDB 11.4+):

Previously, failed SSL connections due to self-signed certificates prevented communication. MariaDB 11.4+ introduces a secondary validation method that works for all servers.

What Happens When SSL Validation Fails?

Even without a valid SSL certificate, the connector can still authenticate by remembering the server's fingerprint (unique identifier). However, it needs to confirm the connection is secure.

Verifying a Secure Connection:

The confirmation method depends on the connection type. When using secure MitM-proof methods, like Unix sockets, connector can automatically validate the connection. Otherwise, a shared secret is used.

Shared Secret for Secure Connection:

The shared secret is only used if the authentication plugin password is hashable (e.g., mysql_native_password or client_ed25519) and not empty. It's calculated by hashing the user's hash password with the authentication seed and the server fingerprint.

Server 11.4+ Confirmation Details:

For servers running MariaDB 11.4 or later, the final confirmation packet contains:

  • int<1> encryption (actually only 0x01 = SHA256 encryption)
  • byte<EOF> shared secret.
Matching the Shared Secret:

If the calculated shared secret matches the received one, the SSL connection is considered valid (host validation is not needed). Otherwise, the connection must be closed for security reasons.

Handshake Response Packet

  • int<4> client capabilities
  • int<4> max packet size
  • int<1> client's default character set and collation
  • string<19> reserved
  • if not (server_capabilities & CLIENT_MYSQL)
    • int<4> extended client capabilities
  • else
  • string<NUL> username
  • if (server_capabilities & PLUGIN_AUTH_LENENC_CLIENT_DATA)
  • else if (server_capabilities & CLIENT_SECURE_CONNECTION)
    • int<1> length of authentication response
    • string<fix> authentication response (length is indicated by previous field)
  • else
  • if (server_capabilities & CLIENT_CONNECT_WITH_DB)
  • if (server_capabilities & CLIENT_PLUGIN_AUTH)
  • if (server_capabilities & CLIENT_CONNECT_ATTRS)

Server Response to Handshake Response Packet

The server responds with an OK_packet, an ERR_packet or an Authentication Switch Request packet.

Authentication Switch Request

(If client and server support CLIENT_AUTH capability)

Plugin List

mysql_old_password Plugin

send a 8 byte encrypted password

authentication plugin data format :

Client response :

mysql_clear_password Plugin

Since password is transmitted in clear, this has be used only when using SSL connection

send clear password to server

Client response :

mysql_native_password Plugin

SHA-1 encrypted password with server seed

authentication plugin data format :

Client response :

The password is encrypted with: SHA1( password ) ^ SHA1( seed + SHA1( SHA1( password ) ) )

dialog Plugin (PAM)

Interactive exchanges to permit fill passwords - for example for 2-Step authentication.

authentication plugin data format :

The server can send one or many requests. For each of them, the client must display this prompt message to the user, to permit the user to type requested information, then send it to the server in string<NUL> format. Password type indicate answer format ( 2 means "read the input with the echo enabled", 4 means "password-like input, echo disabled")

First authentication format (from authentication switch packet) can be empty since 10.4.

This end when server send an EOF_Packet, OK_Packet or ERROR_packet.

auth_gssapi_client Plugin

gssapi implementation

authentication plugin data format :

Client must exchange packet with server until having a mutual GSSAPI authentication. The only difference compared to standard client-server GSSAPI authentication is that exchanges contain standard protocol with packet headers.

client_ed25519 Plugin

The ed25519 plugin uses the Elliptic Curve Digital Signature Algorithm to securely store users' passwords and to authenticate users. It has been Implemented in the server since MariaDB 10.1.22.

See plugin description.

The server sends a random nonce that the client signs.

authentication plugin data format :

Client response :


Server and Client have different capabilities, here is the possibles values.
client with capabilities CLIENT_MYSQL + CONNECT_WITH_DB will have a value of 9 (1 + 8).

CLIENT_MYSQL1Set by older MariaDB versions. MariaDB 10.2 leaves this bit unset to permit MariaDB identification and indicate support for extended capabilities
CONNECT_WITH_DB8One can specify db on connect
COMPRESS32Can use compression protocol
IGNORE_SPACE256Ignore spaces before '('
CLIENT_PROTOCOL_411 << 94.1 protocol
SSL1 << 11Can use SSL
SECURE_CONNECTION1 << 154.1 authentication
MULTI_STATEMENTS1 << 16Enable/disable multi-stmt support
MULTI_RESULTS1 << 17Enable/disable multi-results
PS_MULTI_RESULTS1 << 18Enable/disable multi-results for PrepareStatement
PLUGIN_AUTH1 << 19Client supports plugin authentication
CONNECT_ATTRS1 << 20Client send connection attributes
PLUGIN_AUTH_LENENC_CLIENT_DATA1 << 21Enable authentication response packet to be larger than 255 bytes
CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS1 << 22Client can handle expired passwords
CLIENT_SESSION_TRACK1 << 23Enable/disable session tracking in OK_Packet
CLIENT_DEPRECATE_EOF1 << 24EOF_Packet deprecation :
* OK_Packet replace EOF_Packet in end of Resulset when in text format
* EOF_Packet between columns definition and resultsetRows is deleted
CLIENT_ZSTD_COMPRESSION_ALGORITHM1 << 26Support zstd protocol compression
CLIENT_CAPABILITY_EXTENSION1 << 29Reserved for future use. (Was CLIENT_PROGRESS Client support progress indicator before 10.2)
CLIENT_SSL_VERIFY_SERVER_CERT1 << 30Client verify server certificate. deprecated, client have options to indicate if server certifiate must be verified
MARIADB_CLIENT_PROGRESS1 << 32Client support progress indicator (since 10.2)
MARIADB_CLIENT_EXTENDED_TYPE_INFO1 << 35Add extended metadata information
MARIADB_CLIENT_CACHE_METADATA1 << 36Permit skipping metadata
MARIADB_CLIENT_BULK_UNIT_RESULTS1 << 37when enable, indicate that Bulk command can use STMT_BULK_FLAG_SEND_UNIT_RESULTS flag that permit to return a result-set of all affected rows and auto-increment values

Native Password Authentication

The 20 byte string 'seed' is calculated by concatenating scramble first part (8 bytes) and scramble second part from Initial handshake packet. After that, the client calculates a password hash using the password and seed by using ^ (bitwise xor), + (string concatenation) and SHA1 as follows:

SHA1( passwd) ^ SHA1( seed + SHA1( SHA1( passwd ) ) )


Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.