Bottler Configuration 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 size of a field is a range, it indicates that the
corresponding field has a variable length defined either by an
associated (one or two octet) length field.
Fields taking more than one octet are in network octet 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 USER PAGES
o X'02' LIST USERS
o X'03' MODIFY USERNAME
o X'04' MODIFY PASSWORD
o X'05' ADD USER
o X'06' DELETE USER
o X'07' GET PASSWORD DISSECTOR STATUS
o X'08' SET PASSWORD DISSECTOR
o X'09' GET PROXY AUTHENTICATION STATUS
o X'0A' SET PROXY AUTHENTICATION
3. Commands
3.1. CMD: X'00' - GET METRICS
Requests historical metrics values. Which are historical
connections, current connections and total bytes transmitted.
Connections are represented as an unsigned int taking 4 bytes
Total bytes transmitted as an 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'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
3.2. CMD: X'01' - GET USER PAGES
Requests amount of pages of valid users for the proxy SOCKS
server.
Response comes as an unsigned integer taking 2 bytes representing
amount of pages available containing the usernames of all valid users.
Request:
+-------+-------+---------+
| VER | TOKEN | CMD |
+-------+-------+---------+
| X'01' | 8 | X'01' |
+-------+-------+---------+
Response:
+-------+--------+-------+
| VER | CODE | PAGES |
+-------+--------+-------+
| X'01' | 1 | 2 |
+-------+--------+-------+
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
3.3. CMD: X'02' - LIST USERS
Requests an user page containing usernames of valid users for
the proxy SOCKS server for a given page number.
Response comes as ascii values representing each username
separated by a '\n'. Maximum 5 users per response.
If there are less than 5 then the last username will have
"\n\n" at the end.
Request:
+-------+-------+---------+--------+
| VER | TOKEN | CMD | PAGE |
+-------+-------+---------+--------+
| X'01' | 8 | X'02' | 2 |
+-------+-------+---------+--------+
Response:
+-------+--------+---------------+
| VER | CODE | PAGE SIZE |
+-------+--------+---------------+
| X'01' | 1 | Page size |
+-------+--------+---------------+
PAGE represents a page number greater or equal to 1.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'C0' INVALID PARAMETER VALUE
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
The INVALID PARAMETER VALUE code will be returned when
PAGE value is not a valid page.
3.4. CMD: X'03' - MODIFY USERNAME
Modifies username of user of proxy server.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+-----------+---------+----------+
| VER | TOKEN | CMD | ULEN | UNAME | NULEN | NUNAME |
+-------+-------+---------+--------+-----------+---------+----------+
| X'01' | 8 | X'03' | 1 | 1 to 255 | 1 | 1 to 255 |
+-------+-------+---------+--------+-----------+---------+----------+
Response:
+-------+--------+
| VER | CODE |
+-------+--------+
| X'01' | 1 |
+-------+--------+
UNAME and NUNAME are valid SOCKSv5 usernames. NUNAME
represents the new value for the username of the user
with the username UNAME. ULEN describes the length of
UNAME, NULEN describes the length of NUNAME.
Both UNAME and NUNAME must only contain printable ASCII
characters other than ':'.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'C0' INVALID PARAMETER VALUE
o X'C1' USER NOT FOUND
o X'C1' USER ALREADY EXISTS
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
The INVALID PARAMETER VALUE code will be returned when
ULEN or NULEN is 0 or when there are invalid characters
in either UNAME or NUNAME.
3.5. CMD: X'04' - MODIFY PASSWORD
Modifies password of user of proxy server with username
UNAME.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+-----------+-------+----------+
| VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS |
+-------+-------+---------+--------+-----------+-------+----------+
| X'01' | 8 | X'04' | 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
password of the user with the username UNAME. ULEN
describes the length of UNAME, PLEN describes the
length of PASS.
Both UNAME and PASS must only contain printable ASCII
characters other than ':'.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
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
The INVALID PARAMETER VALUE code will be returned when
ULEN or PLEN is 0 or when there are invalid characters
in either UNAME or PASS.
3.6. CMD: X'05' - ADD USER
Adds a user to the proxy server.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+-----------+-------+----------+
| VER | TOKEN | CMD | ULEN | UNAME | PLEN | PASS |
+-------+-------+---------+--------+-----------+-------+----------+
| X'01' | 8 | X'05' | 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.
Both UNAME and PASS must only contain printable ASCII
characters other than ':'.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'C0' INVALID PARAMETER VALUE
o X'C2' USER ALREADY EXISTS
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
The INVALID PARAMETER VALUE code will be returned when
ULEN or PLEN is 0 or when there are invalid characters
in either UNAME or PASS.
3.7. CMD: X'06' - DELETE USER
Deletes a user from the proxy server.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+-----------+
| VER | TOKEN | CMD | ULEN | UNAME |
+-------+-------+---------+--------+-----------+
| X'01' | 8 | X'06' | 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.
UNAME must only contain printable ASCII
characters other than ':'.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
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
The INVALID PARAMETER VALUE code will be returned when
ULEN or PLEN is 0 or when there are invalid characters
in either UNAME or PASS.
3.8. CMD: X'07' - GET PASSWORD DISSECTOR STATUS
Requests the status of the password dissector service on
the proxy server.
Response comes 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'07' |
+-------+-------+---------+
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 greater than 0 represents
password dissector being active.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
3.9. CMD: X'08' - SET PASSWORD DISSECTOR STATUS
Modifies the status of the password dissector service on
the proxy server.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+
| VER | TOKEN | CMD | STATUS |
+-------+-------+---------+--------+
| X'01' | 8 | X'08' | 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 greater than 0
represents 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'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
3.10. CMD: X'09' - GET PROXY AUTHENTICATION STATUS
Requests the status of the authentication service on the
proxy server.
Response comes 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'09' |
+-------+-------+---------+
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 greater than 0 represents
authentication being active.
The possible values for CODE are:
o X'00' OK
o X'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
3.11. CMD: X'0A' - SET PROXY AUTHENTICATION STATUS
Modifies the status of the authentication service on the
proxy server.
Response comes with a code representing the output of
the action.
Request:
+-------+-------+---------+--------+
| VER | TOKEN | CMD | STATUS |
+-------+-------+---------+--------+
| X'01' | 8 | X'0A' | 1 |
+-------+-------+---------+--------+
Response:
+-------+--------+
| VER | CODE |
+-------+--------+
| X'01' | 1 |
+-------+--------+
STATUS represents the status of the authentication
service. If STATUS is X'00' then authentication
service will be turned off. Any other value greater
than 0 represents authentication 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'A0' SERVER ERROR
o X'B0' INVALID TOKEN
o X'D0' VERSION NOT SUPPORTED
o X'FF' METHOD NOT SUPPORTED
4. Considerations
If an invalid CMD is requested to a server, it must
respond with a package such as:
+-------+--------+
| VER | CODE |
+-------+--------+
| X'01' | X'FE' |
+-------+--------+
Where the CODE X'FE' means that the command is unknown.
5. Authors
Barmasch, Juan MartÃn (61033)
Bellver, Ezequiel (61268)
Lo Coco, Santiago (61301)