Connecting
Contents
Connection is done by many exchanges:
- (Create socket)
- Server sends Initial handshake packet
- If SSL/TLS connection
- Client sends SSLRequest packet and switches to SSL mode for sending and receiving the following messages:
- Client sends Handshake response packet
- Server sends either:
- An OK packet in case of success OK_Packet
- An error packet in case of error ERR_Packet
- Authentication switch
- If the client or server doesn't have PLUGIN_AUTH capability:
- Server sends 0xFE byte
- Client sends old_password
- else
- Server sends Authentication switch request
- Client may have many exchange with the server according to the Plugin.
- Authentication switch ends with server sending either OK_Packet or ERR_Packet
- If the client or server doesn't have PLUGIN_AUTH capability:
Initial Handshake Packet
- int<1> protocol version
- string<NUL> server version (MariaDB server version is by default prefixed by "5.5.5-")
- 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)
- int<1> plugin data length
- else
- int<1> 0x00
- string<6> filler
- if (server_capabilities & CLIENT_MYSQL)
- string<4> filler
- else
- int<4> server capabilities 3rd part . MariaDB specific flags /* MariaDB 10.2 or later */
- if (server_capabilities & CLIENT_SECURE_CONNECTION)
- if (server_capabilities & PLUGIN_AUTH)
- string<NUL> authentication plugin name
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
Handshake Response Packet
- int<4> client capabilities
- int<4> max packet size
- int<1> client character collation
- string<19> reserved
- if not (server_capabilities & CLIENT_MYSQL)
- int<4> extended client capabilities
- else
- string<4> reserved
- string<NUL> username
- if (server_capabilities & PLUGIN_AUTH_LENENC_CLIENT_DATA)
- string<lenenc> authentication 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
- string<NUL> authentication response null ended
- if (server_capabilities & CLIENT_CONNECT_WITH_DB)
- string<NUL> default database name
- if (server_capabilities & CLIENT_PLUGIN_AUTH)
- string<NUL> authentication plugin name
- if (server_capabilities & CLIENT_CONNECT_ATTRS)
- int<lenenc> size of connection attributes
- while packet has remaining data
- string<lenenc> key
- string<lenenc> value
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)
- int<1> 0xFE : Authentication switch request header
- string<NUL> authentication plugin name
- byte<EOF> authentication plugin data
Plugin List
mysql_old_password Plugin
deprecated
send a 8 byte encrypted password
authentication plugin data format :
- byte<8> 8-byte seed
Client response :
- string<NUL> old format encrypted password
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 :
- string<NUL> password without encryption
mysql_native_password Plugin
SHA-1 encrypted password with server seed
authentication plugin data format :
- string<NUL> seed
Client response :
- byte<EOF> sha1 encrypted password
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 :
- byte<1> password type
- string<EOF> prompt message
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 :
- string<NUL> serverPrincipalName (UTF-8 format)
- string<NUL> mechanisms (UTF-8 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 :
- byte<EOF> seed
Client response :
- byte<EOF> ed25519 encrypted password
Capabilities
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_MYSQL | 1 | ||
| FOUND_ROWS | 2 | ||
| CONNECT_WITH_DB | 8 | One can specify db on connect | |
| COMPRESS | 32 | Can use compression protocol | |
| LOCAL_FILES | 128 | Can use LOAD DATA LOCAL | |
| IGNORE_SPACE | 256 | Ignore spaces before '(' | |
| CLIENT_PROTOCOL_41 | 1 << 9 | 4.1 protocol | |
| CLIENT_INTERACTIVE | 1 << 10 | ||
| SSL | 1 << 11 | Can use SSL | |
| TRANSACTIONS | 1 << 12 | ||
| SECURE_CONNECTION | 1 << 13 | 4.1 authentication | |
| MULTI_STATEMENTS | 1 << 16 | Enable/disable multi-stmt support | |
| MULTI_RESULTS | 1 << 17 | Enable/disable multi-results | |
| PS_MULTI_RESULTS | 1 << 18 | Enable/disable multi-results for PrepareStatement | |
| PLUGIN_AUTH | 1 << 19 | Client supports plugin authentication | |
| CONNECT_ATTRS | 1 << 20 | Client send connection attributes | |
| PLUGIN_AUTH_LENENC_CLIENT_DATA | 1 << 21 | Enable authentication response packet to be larger than 255 bytes | |
| CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS | 1 << 2 | Client can handle expired passwords | |
| CLIENT_SESSION_TRACK | 1 << 23 | Enable/disable session tracking in OK_Packet | |
| CLIENT_DEPRECATE_EOF | 1 << 24 | EOF_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_ALGORITHM | 1 << 26 | Support zstd protocol compression | |
| CLIENT_CAPABILITY_EXTENSION | 1 << 29 | reserved for futur use. (Was CLIENT_PROGRESS Client support progress indicator before 10.2) | |
| CLIENT_SSL_VERIFY_SERVER_CERT | 1 << 30 | client verify server certificate | |
| CLIENT_REMEMBER_OPTIONS | 1 << 31 | ||
| MARIADB_CLIENT_PROGRESS | 1 << 32 | Client support progress indicator (since 10.2) | |
| MARIADB_CLIENT_COM_MULTI | 1 << 33 | Permit COM_MULTI protocol | |
| MARIADB_CLIENT_STMT_BULK_OPERATIONS | 1 << 34 | Permit bulk insert | |
| MARIADB_CLIENT_EXTENDED_TYPE_INFO | 1 << 35 | add extended metadata information | |
| MARIADB_CLIENT_CACHE_METADATA | 1 << 36 | permit skipping metadata |
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 ) ) )
