Updated 3-15-2002. BotNet Protocol Specification --------------------------------------- Thus documentation covers BotNet revisions 0x01 through 0x04. The current protocol version is 0x01. The maximum packet length is 511 bytes. The current server revision is 0x04 (Kp_Enhanced). This revision retains full backward compatibility with clients compliant to revisions 0x01, 0x02, or 0x03. As with revision 0x02, this version is not backwards compatible with revision 0x00 clients. This version is significantly stricter in enforcement of protocol. Violations will result in a disconnect; for most violations, the server sends along additional information to help developers identify the nature of the violation. Additions in revision 0x04: * Clients may now perform some actions, such as account management, prior to a status update. Previously, this was forbidden. Operations which transfer any information about the client to other users, such as chat, are still prohibited. * Clients now receive certain information about their access level, such as read/write permission to the current database. * The above-mentioned information is sent in user_stat_update, so clients may now see the access levels of other users. * Significant upgrades to database control. See below for more information. * Additional information is now supplied in the command_over_botnet message. * Additional information is made available at account logon time. Additions in revision 0x03: * Database names are now included in stat updates. Additions in revision 0x02: * Unique account names. By default, everyone has an account name of "No Account". You can log on as an account through message 0x0d. Accounts are guaranteed to be unique (only one instance can be logged on at any given time) and are password protected. Valid characters in account names are: Any alphanumeric characters, and [] brackets. Hence "No Account" cannot be "spoofed" or faked. Account names are given through a new field at the end of the stats change (0x06) message. Note that creating an account does NOT log you on as that account. When you log on as an account, all users on the BotNet will receive a stats change message (0x06) reflecting your new unique account name. * Administrative support. The BotNet server now provides some basic administrative functionality to the server admin. Admin functions are accessed through message 0x0c. You can use the following constants to refer to the new messages and functionality: ("SEND" indicates that the BotNet server sends this message, and "RECV" indicates that the client sends this message). #define ADMIN_MSG_KICK_USER (0x00000000) /* SEND,RECV */ #define ADMIN_MSG_BAN_USER (0x00000001) /* SEND,RECV */ #define ADMIN_MSG_QUERY_USER (0x00000002) /* SEND,RECV */ #define ADMIN_MSG_QUERY_BANS (0x00000003) /* SEND,RECV */ #define ADMIN_MSG_UNBAN (0x00000004) /* SEND,RECV */ #define ADMIN_MSG_NOTIFY_ADMIN_PRIVILEGES (0x00000005) /* SEND */ #define MSG_ID_ADMIN (0x0000000c) /* SEND,RECV */ #define ACCOUNT_MSG_LOGIN (0x00000000) /* SEND,RECV */ #define ACCOUNT_MSG_CHANGE_PASSWORD (0x00000001) /* SEND,RECV */ #define ACCOUNT_MSG_CREATE_ACCOUNT (0x00000002) /* SEND,RECV */ #define MSG_ID_ACCOUNT (0x0000000d) /* SEND,RECV */ Additions to messages will be preceded by the revision number in which the field was added. Packet headers are formed as follows: (BYTE) protocol version (BYTE) packetid (SHORT) packetlen (...) DATA Current packets: (send to server) id 0x00: keepalive (NO DATA) --- there is no response to this packet. You should send this once every 2-3 minutes. (send to client) id 0x00: keepalive (NO DATA) --- the server sends this to the client when the connection has been idle. No response is needed. (send to server) id 0x01: log on to botnet (STRING) bot id (STRING) hub password (send to client) id 0x01: log on status (DWORD) status (0 FAIL 1 OK) (send to server) id 0x02: update bot stats (STRING) unique username on battle.net This field is limited to 15 characters plus the terminating null. Some slack space is allowed by the server, but only the first 15 characters will be retained. Clients violating the slack space will be disconnected. (STRING) current channel on battle.net (DWORD) battle.net server ip (STRING) database id (which database to use) * also now includes database password. Use the following format: "name password". (DWORD) cycle status (0 NOTCYCLING 1 CYCLING) (send to client) id 0x02: update bot stats status (DWORD) status (0 FAIL 1 OK) 0x04: (DWORD) self's access flags (read, write, reserved, restricted) -- (send to server) id 0x03: database modification (DWORD) command command 1: request user database (DWORD) [optional] for incremental database downloads, supply this value as the delta between now and the time at which the increment should begin searching. For instance, for all activity within the past hour, use 3600 (60 seconds * 60 minutes). If not specified, or if the specified value exceeds the server's uptime, the server will perform a full transfer instead. See below to detect this. command 2: add a database entry/modify a database entry (STRING) usermask (STRING) flags (STRING) [optional] comment. The client may place any null-terminated string in this field; it is echoed to other clients on the database when the edit is propogated, but is not saved to disk. Automated clients may wish to place the name of the commanding user in this field (e.g. if [vL]Kp ordered the bot to change a database entry, it would insert "[vL]Kp" for the comment field.) This field is not interpreted by the server in any fashion. If the comment is not enclosed, it is presumed to be the empty string. command 3: remove a database entry (STRING) usermask (STRING) [optional] comment. Same as comment field for subcommand 2. (send to client) id 0x03: database change (DWORD) command command 1: database download control message (DWORD) 0: full database download commencing. The client should purge any information it has in memory. The server will transmit one database edit (3:2) event per user. 1: incremental download starting. The client should _NOT_ purge its existing image. The server will send a database edit (3:2) for all users modified in that period; however, users deleted during the period will result in a database delete message (3:3). 2: database download (either type) completed. Clients are encouraged to use this to re-enable display of database edits, which would normally be suppressed during download due to the sheer volume. command 2: new access list user/modify existing access list user 0x04: (DWORD) ID of client which induced the change. This will be zero if the change originates from the server. The server generates database edit events under two conditions: 1) A client without write access attempted to modify the database. The server will respond to that client with a database edit / delete event to undo the change. 2) A client is downloading a database from the server. 0x04: (DWORD) Timestamp of previous modification to the entry. This will be the present if the entry is being created. (STRING) usermask (STRING) flags 0x04: (STRING) comment field. If the update was caused by a client, this field contains any information the client sent along. If the update is induced by the server, it will contain the string "auto-reverse" for condition 1 (read-only edit being countered) or the empty string "" for a database download. command 3: remove a database entry 0x04: (DWORD) ID of client, or zero if the change originates from the server. 0x04: (DWORD) Timestamp of previous modification. (STRING) usermask 0x04: (STRING) Comment from originating entity. All fields in this message serve the same purpose as in subcommand 2. -- (send to server) id 0x04: command to bots on same database (STRING) sending user (STRING) command (send to client) id 0x04: command over botnet 0x04: (DWORD) ID of sending client. 0x04: (DWORD) Subtype code. Zero for broadcast commands, 1 for commands to users on the same database, and 2 for directed commands. (STRING) sender (STRING) command (send to server) id 0x05: cycle request (DWORD) count (STRING LIST) usernames of bots to cycle (send to client) id 0x05: cycle request notification (STRING) channel to cycle (send to server) id 0x06: request information about bots on botnet (send to client) id 0x06: botnet bot information (DWORD) bot id 0x04: (DWORD) Client's access (read, write, reserved, restricted) (STRING) bot name (STRING) bot channel (DWORD) bot server 0x02: (STRING) unique account name 0x03: (STRING) database name (send to server) id 0x07: command over botnet to all botnet bots (send 0x04 to client) Note that this is treated as a command 0x04 when sent from non-administrators. (STRING) sending user (STRING) command (send to client) id 0x07: bot disconnecting from botnet (DWORD) bot id (send to server) id 0x08: command to specific botnet bot (send 0x04 to client) (DWORD) target bot id (STRING) sending user (STRING) command (send to client) id 0x08: protocol violation detected (DWORD) violating command ID# (DWORD) length of violating packet (DWORD) number of unprocessed bytes following that packet (send to server) id 0x09: change database password * Requires 'full' access (DWORD) password to change (0: readonly, 1: full, 2: restricted) (STRING) new password (send to client) id 0x09: acknowledge client's 0x0a (DWORD) server version at which communication will occur. This value is never above, but may be below, the value indicated in the client's first dword of 0x0a. The intent is that if a version 2 aware client logs onto a version 1 server, the server can indicate that it will only behave in version 1 fashion, rather than version 2. (send to server) id 0x0a: maximum botnet server version known (DWORD) version -- this is the highest revision the client is aware of. Zero requests legacy mode support (that is, pre-Kp behavior). This is assumed if no message is sent. In legacy behavior, the fields marked "0x04" in this document will not appear. (DWORD) client capabilities -- bitmask, currently only bit 0 is defined. Bit zero corresponds to AWAIT_DB_ACKNOWLEDGE -- clients will _NOT_ update their local access list until the server echoes the behavior back. Therefore, the server will silently ignore edits/deletes from read-only clients in this mode. Additionally, successful changes from clients _not_ in this mode will receive no response (but will be distributed to other clients on the database, and committed to file). (send to client) id 0x0a: botnet server version (DWORD) version --- current version '2'. This will change when new features are added. Thus, you will know what features a particular botnet server supports right away. This is sent before logon confirmation. Version information: Version 1 supports all packets 0x00 through 0x0b. Version 2 supports messages 0x0c and 0x0d. Version 3 adds database names to statupdate. Version 4 adds support for C->S 0xa, and all other features marked by "0x04" in this document. (send to server) id 0x0b: botnet chat (DWORD) command --- 0x00: message to all bots, 0x01: message to bots on the same database, 0x02: message to bot specified by id. (DWORD) action --- 0x00: talk, 0x01: emote (DWORD) id --- for command 0x02, id of bot to send to, otherwise ignored. (STRING) message --- chat message to send. (send to client) id 0x0b: botnet chat (DWORD) command --- 0x00: message to all bots, 0x01: message to bots on the same database, 0x02: message to bot specified by id. (DWORD) action --- 0x00: talk, 0x01: emote (DWORD) id --- id of source bot (for all commands) (STRING) message --- chat message sent. (send to server) id 0x0d: account management (DWORD) subcommand * Subcommand 0x00: Login: (STRING) account name (STRING) account password * Subcommand 0x01: Change password: (STRING) account name (STRING) old password (STRING) new password * Subcommand 0x02: Account create: (STRING) account name (STRING) account password Other subcommand values are reserved for future use. (send to client) id 0x0d: account management reply (DWORD) subcommand --- This is the same subcommand as the message being replied to. (DWORD) BOOLEAN TRUE(1)/FALSE(0) : Success/Failure for subcommand subcommand 0: [in addition to success code] (DWORD) if successful, this is the last IP address from which a successful logon was performed. If the logon failed, this is zero if the failure was due to an invalid logon, or one if it failed because the account is already in use. Note that an invalid logon means either the account does not exist, or the password is wrong.