476 lines
17 KiB
Plaintext
476 lines
17 KiB
Plaintext
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.
|
|
|
|
Also, 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)
|