Bottler Protocol version 1 1. Introduction The ability to get statistics or configure a certain server is imperative, this protocol provides a way to do it remotely. Note: Unless otherwise noted, the decimal numbers appearing in packet - format diagrams represent the length of the corresponding field, in octets. Where a given octet must take on a specific value, the syntax X'hh' is used to denote the value of the single octet in that field. When the word 'Variable' is used, it indicates that the corresponding field has a variable length defined either by an associated (one or two octet) length field, or by a data type field. NETWORK ORDER!!! 2. Requests The requested is formed as follows: +-----+-------+-------+--------------+ | VER | TOKEN | CMD | PARAMETERS | +-----+-------+-------+--------------+ | 1 | 8 | 1 | 0 to 255 | +-----+-------+-------+--------------+ The VER field is set to X'01' for this version of the protocol. The TOKEN field contains 8 bytes that authenticates the request. The CMD field describes the command that will be run. The PARAMETERS field describes the parameters that will be passed depending on the CMD field value. The values currently defined for CMD are: o X'00' GET METRICS o X'01' GET BUFFER SIZE o X'02' SET BUFFER SIZE o X'03' GET TIMEOUT VALUE o X'04' SET TIMEOUT VALUE o X'05' GET USER PAGES o X'06' LIST USERS o X'07' GET USER LAST CONNECTION o X'08' MODIFY USERNAME o X'09' MODIFY PASSWORD o X'0A' ADD USER o X'0B' DELETE USER o X'0C' GET PASSWORD DISSECTOR STATUS o X'0D' ENABLE/DISABLE PASSWORD DISSECTOR o X'0E' GET PROXY AUTHENTICATION STATUS o X'0F' ENABLE/DISABLE PROXY AUTHENTICATION o X'10' GET PROXY SERVER STATUS o X'11' START/STOP PROXY SERVER o X'12' RESET PROXY SERVER TODO: metodo para saber cuanto tiene una página? o lo hardcodeamos en el proto? TODO: unknown command 0xFE TODO: get users de ettercap (not quite) 2. Commands CMD: X'00' - GET METRICS Requests historical metrics values. Which are hostorical connections, current connections and total bytes transmited. Connections are represented as an unisgned int taking 4 bytes Total bytes transmited as a unsigned long taking 8 bytes. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'00' | +-------+-------+---------+ Response: +-------+--------+------------+-----------+-------------+ | VER | CODE | TOTAL CONN | CURR CONN | TOTAL BYTES | +-------+--------+------------+-----------+-------------+ | X'01' | 1 | 4 | 4 | 8 | +-------+--------+------------+-----------+-------------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'01' - GET BUFFER SIZE Requests buffer size used for the proxy SOCKS server. Response comes with a response code and one integer representing the buffer size taking 2 bytes. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'01' | +-------+-------+---------+ Response: +-------+--------+-----------+ | VER | CODE | BUFF SIZE | +-------+--------+-----------+ | X'01' | 1 | 2 | +-------+--------+-----------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'02' - SET BUFFER SIZE TODO: decidir bien los tamaños Requests the modification of the buffer size used for the proxy SOCKS server. Value must be between 256 and 16.384 Response comes with a response code indicating the output of the action required Request: +-------+-------+---------+-----------+ | VER | TOKEN | CMD | BUFF SIZE | +-------+-------+---------+-----------+ | X'01' | 8 | X'02' | 2 | +-------+-------+---------+-----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'03' - GET TIMEOUT VALUE Requests the timeout value used in the proxy SOCKS server. Response comes with a response code and one integer representing the timeout value taking 2 bytes. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'03' | +-------+-------+---------+ Response: +-------+--------+---------+ | VER | CODE | TIMEOUT | +-------+--------+---------+ | X'01' | 1 | 2 | +-------+--------+---------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'04' - SET TIMEOUT VALUE TODO: decidir bien los valores Requests the modification of the timeout value used in the proxy SOCKS server. Value must be between 128 and 2048 Response comes with a response code indicating the output of the action required Request: +-------+-------+---------+---------+ | VER | TOKEN | CMD | TIMEOUT | +-------+-------+---------+---------+ | X'01' | 8 | X'04' | 2 | +-------+-------+---------+---------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'05' - GET USER PAGES Requests amount of pages of valid users for the proxy SOCKS server. Response comes as an integers taking 2 bytes. (representing) Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'05' | +-------+-------+---------+ Response: +-------+--------+-------+ | VER | CODE | PAGES | +-------+--------+-------+ | X'01' | 1 | 2 | +-------+--------+-------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'06' - LIST USERS Requests amount of pages of valid users for the proxy SOCKS server. Response comes as an integers taking 2 bytes. (representing) Request: +-------+-------+---------+--------+ | VER | TOKEN | CMD | PAGE | +-------+-------+---------+--------+ | X'01' | 8 | X'06' | 2 | +-------+-------+---------+--------+ Response: +-------+--------+---------------+ | VER | CODE | PAGE | +-------+--------+---------------+ | X'01' | 1 | Page size | +-------+--------+---------------+ The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'08' - MODIFY USERNAME Modifies username of user of proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+---------+----------+ | VER | TOKEN | CMD | ULEN | UNAME | NULEN | NUNAME | +-------+-------+---------+--------+-----------+---------+----------+ | X'01' | 8 | X'08' | 1 | 1 to 255 | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+---------+----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME and NUNAME are valid SOCKSv5 usernames. NUNAME represents de new value for the username of the user with the username UNAME. ULEN describes the length of UNAME, NULEN describes the length of NUNAME. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'09' - MODIFY PASSWORD Modifies password of user of proxy server with username UNAME. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+-------+----------+ | VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS | +-------+-------+---------+--------+-----------+-------+----------+ | X'01' | 8 | X'09' | 1 | 1 to 255 | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+-------+----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username and PASS is a valid SOCKSv5 password. PASS represents de new value for the passowrd of the user with the username UNAME. ULEN describes the length of UNAME, PLEN describes the length of PASS. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0A' - ADD USER Adds a user to the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+-------+----------+ | VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS | +-------+-------+---------+--------+-----------+-------+----------+ | X'01' | 8 | X'0A' | 1 | 1 to 255 | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+-------+----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username and PASS is a valid SOCKSv5 password. UNAME represents the value for the username of the new user and PASS represents the value for the password of user. ULEN describes the length of UNAME, PLEN describes the length of PASS. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0B' - DELETE USER Deletes a user from the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+ | VER | TOKEN | CMD | ULEN | UNAME | +-------+-------+---------+--------+-----------+ | X'01' | 8 | X'0B' | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username. UNAME represents the value for the username of the user to be deleted. ULEN describes the length of UNAME. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0C' - GET PASSWORD DISSECTOR STATUS Requests the status of the password dissector service on the proxy server. Response comes as with a code representing the output of the action and a STATUS representing the status of the password dissector. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'0C' | +-------+-------+---------+ Response: +-------+--------+--------+ | VER | CODE | STATUS | +-------+--------+--------+ | X'01' | 1 | 1 | +-------+--------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then password dissector service is down. Any other value representes password dissector being active. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0D' - SET PASSWORD DISSECTOR STATUS Modifies the status of the password dissector service on the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+ | VER | TOKEN | CMD | STATUS | +-------+-------+---------+--------+ | X'01' | 8 | X'0D' | 1 | +-------+-------+---------+--------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then password dissector service will be turned off. Any other value representes password dissector being turned on. In case that the STATUS value is the same of the password dissector service's then the instruction will be ignored. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0E' - GET PROXY AUTHENTICATION STATUS Requests the status of the authentication service on the proxy server. Response comes as with a code representing the output of the action and a STATUS representing the status of the authentication service. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'0E' | +-------+-------+---------+ Response: +-------+--------+--------+ | VER | CODE | STATUS | +-------+--------+--------+ | X'01' | 1 | 1 | +-------+--------+--------+ STATUS represents the status of the authentication service. If STATUS is X'00' then authentication service is down. Any other value representes authentication being active. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0F' - SET PROXY AUTHENTICATION STATUS Modifies the status of the authentication service on the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+ | VER | TOKEN | CMD | STATUS | +-------+-------+---------+--------+ | X'01' | 8 | X'0F' | 1 | +-------+-------+---------+--------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then authentication service will be turned off. Any other value representesauthentication being turned on. In case that the STATUS value is the same of the password dissector service's then the instruction will be ignored. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED 3. Replies The SOCKS request information is sent by the client as soon as it has established a connection to the SOCKS server, and completed the authentication negotiations. The server evaluates the request, and returns a reply formed as follows: +-----+-----+ | VER | REP | +-----+-----+ | 1 | 1 | +-----+-----+ Where: o VER protocol version: X'05' o REP Reply field: o X'00' succeeded o X'01' general SOCKS server failure o X'02' connection not allowed by ruleset o X'03' Network unreachable o X'04' Host unreachable o X'05' Connection refused o X'06' TTL expired o X'07' Command not supported o X'08' Address type not supported o X'09' to X'FF' unassigned 9. References The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'09' - MODIFY PASSWORD Modifies password of user of proxy server with username UNAME. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+-------+----------+ | VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS | +-------+-------+---------+--------+-----------+-------+----------+ | X'01' | 8 | X'09' | 1 | 1 to 255 | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+-------+----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username and PASS is a valid SOCKSv5 password. PASS represents de new value for the passowrd of the user with the username UNAME. ULEN describes the length of UNAME, PLEN describes the length of PASS. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0A' - ADD USER Adds a user to the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+-------+----------+ | VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS | +-------+-------+---------+--------+-----------+-------+----------+ | X'01' | 8 | X'0A' | 1 | 1 to 255 | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+-------+----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username and PASS is a valid SOCKSv5 password. UNAME represents the value for the username of the new user and PASS represents the value for the password of user. ULEN describes the length of UNAME, PLEN describes the length of PASS. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0B' - DELETE USER Deletes a user from the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+-----------+ | VER | TOKEN | CMD | ULEN | UNAME | +-------+-------+---------+--------+-----------+ | X'01' | 8 | X'0B' | 1 | 1 to 255 | +-------+-------+---------+--------+-----------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ UNAME is a valid SOCKSv5 username. UNAME represents the value for the username of the user to be deleted. ULEN describes the length of UNAME. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'C0' INVALID PARAMETER VALUE o X'C1' USER NOT FOUND o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0C' - GET PASSWORD DISSECTOR STATUS Requests the status of the password dissector service on the proxy server. Response comes as with a code representing the output of the action and a STATUS representing the status of the password dissector. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'0C' | +-------+-------+---------+ Response: +-------+--------+--------+ | VER | CODE | STATUS | +-------+--------+--------+ | X'01' | 1 | 1 | +-------+--------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then password dissector service is down. Any other value representes password dissector being active. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0D' - SET PASSWORD DISSECTOR STATUS Modifies the status of the password dissector service on the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+ | VER | TOKEN | CMD | STATUS | +-------+-------+---------+--------+ | X'01' | 8 | X'0D' | 1 | +-------+-------+---------+--------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then password dissector service will be turned off. Any other value representes password dissector being turned on. In case that the STATUS value is the same of the password dissector service's then the instruction will be ignored. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0E' - GET PROXY AUTHENTICATION STATUS Requests the status of the authentication service on the proxy server. Response comes as with a code representing the output of the action and a STATUS representing the status of the authentication service. Request: +-------+-------+---------+ | VER | TOKEN | CMD | +-------+-------+---------+ | X'01' | 8 | X'0E' | +-------+-------+---------+ Response: +-------+--------+--------+ | VER | CODE | STATUS | +-------+--------+--------+ | X'01' | 1 | 1 | +-------+--------+--------+ STATUS represents the status of the authentication service. If STATUS is X'00' then authentication service is down. Any other value representes authentication being active. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED CMD: X'0F' - SET PROXY AUTHENTICATION STATUS Modifies the status of the authentication service on the proxy server. Response comes as with a code representing the output of the action. Request: +-------+-------+---------+--------+ | VER | TOKEN | CMD | STATUS | +-------+-------+---------+--------+ | X'01' | 8 | X'0F' | 1 | +-------+-------+---------+--------+ Response: +-------+--------+ | VER | CODE | +-------+--------+ | X'01' | 1 | +-------+--------+ STATUS represents the status of the password dissector service. If STATUS is X'00' then authentication service will be turned off. Any other value representesauthentication being turned on. In case that the STATUS value is the same of the password dissector service's then the instruction will be ignored. The possible values for CODE are: o X'00' OK o X'B0' INVALID TOKEN o X'D0' VERSION NOT SUPPORTED o X'FF' METHOD NOT SUPPORTED 3. Replies The SOCKS request information is sent by the client as soon as it has established a connection to the SOCKS server, and completed the authentication negotiations. The server evaluates the request, and returns a reply formed as follows: +-----+-----+ | VER | REP | +-----+-----+ | 1 | 1 | +-----+-----+ Where: o VER protocol version: X'05' o REP Reply field: o X'00' succeeded o X'01' general SOCKS server failure o X'02' connection not allowed by ruleset o X'03' Network unreachable o X'04' Host unreachable o X'05' Connection refused o X'06' TTL expired o X'07' Command not supported o X'08' Address type not supported o X'09' to X'FF' unassigned 9. References