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)