BNETDocs
BotNet Protocol Overview

BotNet is a Valhalla Legends-made service designed for inter-bot communication.

Like Classic Battle.net, it is a lightweight, unencrypted binary protocol. It was originally made to share the "databases" of bots and act as a possible system for load balancing and moderation. It was expanded to support chat, and is now hosted by BNETDocs at botnet.bnetdocs.org (see server list).

By convention, the server runs on TCP port 21845 (that is, hexadecimal 0x5555).

For clarity, there are several ambiguous terms this website uses distinctly in regards to this protocol and especially its fields:

  • version (ver) refers to the "protocol version" which is always 0x01. It is in every message header.
  • revision (rev) refers to the "server revision" which is one of 0x01 through 0x04. It is sent by the server in S>C 0x0A BOTNET_REVISION.
  • awareness level (awl) refers to the "client protocol awareness level" which is either 0x00 (default) or 0x01. It is set by the client in C>S 0x0A BOTNET_CLIENT_VERSION.
  • max length (max) refers to the maximum number of bytes a null-terminated string can be accepted at, including the null terminator.

Databases

BotNet was originally designed to share the user databases between groups of bots, so that the network can agree on permissions Battle.net users had. A database entry is a Usermask and Flags pair, conventionally describing a user or group of users on Battle.net and their permissions to the bot(s) using the database in the form of uppercase flags from A through Z.

This database of user permissions, as well as chat and inter-bot commands, are all designed around this "database" construct, which clients request access to right after log on.

If an invalid database name and password is sent in C>S 0x02 BOTNET_STATSUPDATE, the server places the user in a read-only "public" database with the name set to an empty string.

Accounts

Starting with server revision 2, users can create and log on to accounts using C>S 0x0D BOTNET_ACCOUNT/S>C.

Account names are restricted to alphanumeric characters, brackets, underscores, and dashes, A-Za-z0-9[]_-. Invalid characters result in failure to create and to log on to the account.

This account name appears in S>C 0x06 BOTNET_USER when you successfully log on. Users who are not logged on appear with the string "No Account" which is not a valid account name.

The server ensures that there is never more than one user online using a given account name. When a client logs on with a second connection using the same account, the other user is changed to no longer be on an account.

Account passwords are plaintext and sent over an unencrypted protocol so it is advised that it is not shared with any other website or service for your own safety.

Administrative access

Administrative access on BotNet is specified by a set of flags that accounts can have.

They are stored in a UINT32 and conventionally decoded as a series of 26 bits where each one refers to a letter of the alphabet from A to Z.

Defined flags:

  • A = Superuser: can perform any administrative action.
  • B = Broadcast: may use talk-to-all.
  • C = Connection: may administer botnet connectivity.
  • D = Database: may create and maintain databases.
  • I = ID control: may create and modify hub IDs.
  • S = BotNet service.

BotNet Protocol

Every BotNet message has the same header:

 (UINT8) Protocol version
 (UINT8) Message ID
(UINT16) Message length, including this header
  (VOID) Message data

Messages have a maximum size of 511 bytes.

Server Revisions

There have been 4 revisions to the server software, which are denoted in message structures by [rev: #]. If none is supplied, all revisions send/expect that field.

  1. Initial server revision.
  2. Added account names and administration functions.
  3. Database is now provided in user update messages.
  4. Added messages for protocol violation, client capabilities and awareness, and chat options.

Message Index

Dir ID Name Description
C>S 0x00 BOTNET_KEEPALIVE Keep the connection alive
S>C 0x00 BOTNET_KEEPALIVE Keep the connection alive
C>S 0x01 BOTNET_LOGON Identify yourself with BotNet
S>C 0x01 BOTNET_LOGON Acknowledge identifying yourself with BotNet
C>S 0x02 BOTNET_STATSUPDATE Update client information
S>C 0x02 BOTNET_STATSUPDATE Acknowledge client information
C>S 0x03 BOTNET_DATABASE Request and manipulate database data
S>C 0x03 BOTNET_DATABASE Database data updated
C>S 0x04 BOTNET_COMMAND_TO_DATABASE Command to bots on your database
S>C 0x04 BOTNET_COMMAND Receive command over BotNet
C>S 0x05 BOTNET_CYCLE Send cycle request (defunct)
S>C 0x05 BOTNET_CYCLE Receive cycle request (defunct)
C>S 0x06 BOTNET_USER_LIST Request the user list from BotNet
S>C 0x06 BOTNET_USER User information updated
C>S 0x07 BOTNET_COMMAND_TO_ALL Command to all bots
S>C 0x07 BOTNET_USER_DISC User disconnected
C>S 0x08 BOTNET_COMMAND_TO Command to specific bot
S>C 0x08 BOTNET_PROTOCOL_VIOLATION Client violated protocol
C>S 0x09 BOTNET_DATABASE_CHPW Change the database's password
S>C 0x09 BOTNET_CLIENT_VERSION Acknowledge client awareness level
C>S 0x0A BOTNET_CLIENT_VERSION Set client awareness level and capabilities
S>C 0x0A BOTNET_REVISION Alert specifying server revision
C>S 0x0B BOTNET_CHAT Send chat
S>C 0x0B BOTNET_CHAT Receive chat
C>S 0x0C BOTNET_ADMIN Use admin features
S>C 0x0C BOTNET_ADMIN Use admin features
C>S 0x0D BOTNET_ACCOUNT Log on to, create, or modify account
S>C 0x0D BOTNET_ACCOUNT Response to logging on to, creating, or modifying account
C>S 0x0E BOTNET_DATABASE_CHMO Send database change mode request (defunct)
S>C 0x0E BOTNET_DATABASE_CHMO Acknowledge database change mode request (defunct)
C>S 0x10 BOTNET_CHAT_OPTIONS Set chat options
S>C 0x10 BOTNET_CHAT_OPTIONS Acknowledge chat options

Logon Sequence

By convention, you should log on to the service by sending and accepting this sequence of messages:

  1. C>S 0x01 BOTNET_LOGON: Log on using assigned bot name and password.
  2. (optional) C>S 0x0A BOTNET_CLIENT_VERSION: Send client awareness level and capabilities, if not 0, 0 [rev: 4].
  3. (optional) C>S 0x10 BOTNET_CHAT_OPTIONS: Send chat options, if not 0, 0, 0, 0 [rev: 4].
  4. (optional) C>S 0x0D BOTNET_ACCOUNT: Log on to account [rev: 2].
    • S>C 0x0D BOTNET_ACCOUNT: Server responds to logon.
    • Clients should try creating a non-existent account here using the subcommand in 0x0D.
    • Developers should avoid allowing clients to fail account logon in loops if creation fails.
    • Clients should wait on 0x02 (the following message) until account logon is resolved to avoid sending double updates to other users.
  5. C>S 0x02 BOTNET_STATSUPDATE: Update your information as it appears on Battle.net, and specify a database to use.
  6. (optional) C>S 0x06 BOTNET_USER_LIST: Request online users, if you want to know who is there.
    • S>C 0x06 BOTNET_USER []: A sequence of these is received. The first one is the requesting client. For awareness level 1 clients, this is followed by a 4-byte "null" indicator message, which is just the 0x06 message but blank. Otherwise, no "null" indicator is sent and it may be advisable to send another message after 0x06 to determine its end for server revisions before 4.
  7. (optional) C>S 0x03 BOTNET_DATABASE: Request current database contents, if you want to know what is there.
  8. Of course, you are free to use the other messages depending on what the user or application requires. The above is just a guideline so you can know where to go to implement the protocol.
| Edited: Ribose
Comments

no one has commented yet.