# Mikrotik MAC Telnet protocol # Author: Omni Flux # Revision: 02 # Most recent version is available at http://www.omniflux.com/devel/ # # Changelog: # Revision 02: # * Document idle acknowledgement packets # * Add control packet type 7 # * Diagram control packet # * Add missing length field in control packets (thanks, Håkon Nessjøen) # * Remove incorrect 'contains null byte in variable data section' from some # control packets (actually part of length field) -------------------------------------------------------------------------------- The following document is based on observations of Mikrotik's MAC Telnet client for Windows "terminal.exe" and RouterOS 3.28 running on an RB493AH. It is not authoritative, probably missing information, and may even have some inaccuracies. The Mikrotik MAC Telnet protocol is not actually an implementation of telnet on the link layer; it is a completely different protocol using UDP which in no way resembles IETF Internet Standard STD 8 AKA RFCs 854 and 855. The protocol described below is encapsulated in UDP packets with the following values: Source port 20561 Destination port 20561 Client destination IP address 255.255.255.255 Client destination MAC address ff:ff:ff:ff:ff:ff Server destination IP address 255.255.255.255 Server destination MAC address Sessions -------- A MAC telnet session is composed of four stages: - The client requests a session from the server - The client authenticates to the server - The client is connected to a remote shell - The server terminates a session Each session contains a unique session ID generated by the client. Example conversation -------------------- C->S: Open session C->S: Begin authentication S->C: Supplies encryption key C->S: Supplies authentication details (including terminal details) S->C: End authentication User can interact with the remote shell OR User receives a login failed message S->C: End session C->S: End session NOTE ---- After authentication, the client may send packets informing the server of changes in the clients terminal size. UDP Payload ----------- 0 1 2 3 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ver (1) | ptype (1) | srcaddr (6) | +---------------+---------------+---------------+---------------+ | srcaddr (6) | +-------------------------------+-------------------------------+ | dstaddr (6) | +-------------------------------+-------------------------------+ | dstaddr (6) | seskey (4) | +---------------------------------------------------------------+ | seskey (4) | counter (4) | +---------------------------------------------------------------+ | counter (4) | variable data | +---------------------------------------------------------------+ FIELD OCTETS DESCRIPTION ----- ------ ----------- ver 1 Unknown - Probably protocol version ptype 1 Packet type srcaddr 6 Source MAC address dstaddr 6 Destination MAC address seskey 4 Session key and client type counter 4 Session sent/received byte counter ver --- This field contains the value 0x01 in all observed packets. It is probably the protocol version. ptype ----- This field specifies one of the following packet types: TYPE DESCRIPTION ---- ----------- 0 Start session 1 Data 2 Acknowledge 255 End session A start session packet should be sent once, by the client, to begin a session. An end session packet should be sent once by the server to terminate a session; the client should respond with an end session packet. An acknowledge packet should be sent in response to every start session and data packet. If an acknowledge packet is not received within 15,000 microseconds, the unacknowledged packet should be retransmitted at the following intervals: +0, +5,000, +10,000, +20,000, +40,000, +80,000, +160,000 microseconds. If acknowledgement has not been received after the final retransmission, the session is terminated with no end session packet sent. An acknowledgement packet should also be sent from both the server and the client after ten seconds of no other transmissions to keep a session open. srcaddr ------- This field contains the packet senders MAC address. dstaddr ------- This field contains the packet recipients MAC address. seskey ------ This field contains a two byte client generated key unique to each session and a two byte client type identifier. The MAC telnet client identifier is 0x0015. The WinBox client identifier is 0x0f90 Packets sent from the client will have these bytes ordered as 0xabcd0015. Packets sent from the server will have these bytes ordered as 0x0015abcd. counter ------- This field contains a count of the number of variable data bytes sent during the current session not including the current packet, or the number of variable data bytes received during the current session if the packet is an acknowledgement packet. variable data ------------- This field is used only with the Data packet type. If the field begins with the value 0x563412ff then it is a control packet. Any other data is either from or for the remote shell. Multiple control packet sections may be contained in one data packet. Control packets --------------- 0 1 2 3 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | control packet magic number (4) | +---------------+---------------+---------------+---------------+ | type (1) | length (4) | +---------------------------------------------------------------+ | length (4) | variable data | +---------------------------------------------------------------+ FIELD OCTETS DESCRIPTION ----- ------ ----------- magic 4 Control packet magic number type 1 Control packet type length 4 Length of control packet variable data magic ----- This field contains the magic number 0x563412ff. type ----- This field specifies one of the following control packet types: NUMBER DESCRIPTION ------ ----------- 0 Begin authentication 1 Encryption key 2 Password 3 Username 4 Terminal type 5 Terminal width 6 Terminal height 7 Unknown - Possibly received invalid control packet 9 End authentication length ----- This field specifies the length in bytes of the variable data field. Control packet types -------------------- Begin authentication -------------------- This is the first data packet sent by the client to the server. It contains no variable data. It is neither preceded nor followed by any other data sections. The server should respond with an encryption key control packet. Encryption key -------------- This is sent in response to a clients begin authentication control packet. It contains an encryption key. It is neither preceded nor followed by any other data sections. The client should respond with a control packet containing authentication and terminal information. Password -------- This is sent in response to a servers encryption key control packet. It contains a null byte followed by an MD5 digest of a null character concatenated with the users password and the encryption key. It is not preceded by any data sections, but is followed by a username data section. The server should respond with an end authentication control packet. Username -------- This is sent in response to a servers encryption key control packet. It contains the username. It is preceded by a password data section and followed by a terminal type data section. Terminal type ------------- This is sent in response to a servers encryption key control packet. It contains the terminal type. This field contains the value "linux" in all observed packets. It is preceded by a username data section and followed by a terminal width data section. Terminal width -------------- This is sent in response to a servers encryption key control packet OR when the client wishes to inform the server of a change in the clients terminal size. It contains two bytes specifying the character width of the client terminal. It is preceded by a terminal type data section when sent in response to an encryption key control packet and by nothing when notifying the server of a change in the clients terminal size. It is followed by a terminal height data section. Terminal height -------------- This is sent in response to a servers encryption key control packet OR when the client wishes to inform the server of a change in the clients terminal size. It contains two bytes specifying the character height of the client terminal. It is preceded by a terminal width data section and is not followed by any other data sections. End authentication ------------------ This is sent by the server in response to a client control packet containing authentication information. It contains no variable data. It is neither preceded nor followed by any other data sections. This packet does *not* indicate whether authentication was successful or not. The packet containing this data section is sent twice in all observed sessions. This data section is neither preceded nor followed by any other data sections. The server follows up by: Sending either a data packet with the message "Login failed, incorrect username or password" followed by an end session packet. OR Sending the output of the remote shell and waiting for input from the client. Other data ---------- Other data sent from the client to the server is meant as input to the remote shell. In all observed packets of this type from the client to the server, the data section contains one byte, a character input by the user. Data of this type sent from the server to the client is meant as output for the user. Newline and carriage return should be handled separately. Output often contains escape codes not documented here.