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-list|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)
- int<1> length of scramble's 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
- int<1> 0x00
- 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
- loop {
- string<lenenc> key
- string<lenenc> value
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
plugin "mysql_old_password"
deprecated
send a 8 byte encrypted password
authentication plugin data format :
- byte<8> 8-byte seed
Client response :
- string<NUL> old format encrypted password
plugin "mysql_clear_password"
deprecated
send clear password to server
Client response :
- string<NUL> password without encryption
plugin "mysql_native_password"
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 ) ) )
plugin "dialog"
Interractive exchanges to permit fill passwords - for example for 2-Step authentication.
Server can send one or many request, each containing a prompt in string<EOF> format. For each of them, client must display this prompt to user, to permit user to type requested informations, then send it to server in string<NUL> format.
First prompt value is contain in Authentication plugin data ( in string<EOF> format).
This end when server send an EOF_Packet, OK_Packet or ERROR_packet.
plugin "auth_gssapi_client"
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 compare to standard client-server GSSAPI authentication is that exchanges contain standard protocol with packet headers.
plugin "client_ed25519"
The ed25519 plugin uses Elliptic Curve Digital Signature Algorithm to securely store users' passwords and to authenticate users. Implemented in server since 10.1.22.
See plugin description.
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_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 |
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 |
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 ) ) )