BNLS Packet Guide

This document guides a first-time developer on how to use Battle.net and BNLS together, as often it could be confusing at first.

Standard Procedures & Tips

• Bots are not required to authenticate themselves with the BNLS they've chosen, but it doesn't hurt if they do and is always a friendly greeting to the operator of the chosen BNLS host.
• A proper implementation of BNLS means the user should never be asked for a version byte and the bot shouldn't have to store one. This is because the bot should request it from BNLS using BNLS_REQUESTVERSIONBYTE.
• Most bots should never send CD-keys or passwords to BNLS. This is because BNLS is an unencrypted/plaintext protocol and therefore this sensitive data could be intercepted and stolen. It is even possible to run a rogue BNLS that captures this data in the background while behaving as normal. The proper solution is to locally hash CD-keys and passwords using standard open-source libraries. BNETDocs has a few of these on GitHub.
• In case it's not obvious, for the most part BNLS packets are named identical or nearly identical to their Battle.net counterpart. You can think of them as pairs or twins. As an example, the SID_AUTH_ACCOUNTCREATE packet complements BNLS_CREATEACCOUNT.
• OLS refers to the Old Logon System and NLS refers to the New Logon System, see SID_AUTH_INFO for specifics.
• Most bots will likely only use BNLS for version checks. This is a very short process, as it means sending a BNLS_VERSIONCHECKEX2 and receiving it back, then disconnecting. This is also why you will receive the latest version byte in response, this is so it can be stored for later and automagically updated each time the bot performs a version check.

Messages

BNLS_AUTHORIZE and BNLS_AUTHORIZEPROOF:

• These authenticate a bot to the BNLS host. They are not required to be sent. However, doing so is a friendly greeting to the operator of the BNLS that's chosen.
• The bot id should be the name of your bot to be presented in print, not a username or some other value.

BNLS_REQUESTVERSIONBYTE:

• This requests the latest version byte for a given product.

BNLS_VERSIONCHECK, BNLS_VERSIONCHECKEX, and BNLS_VERSIONCHECKEX2:

• These are to be used with any of the version check systems Battle.net uses. Most will probably only use the latest BNLS_VERSIONCHECKEX2 packet as it is the most complete and versatile.

BNLS_CDKEY and BNLS_CDKEY_EX:

• These packets are used for hashing the user's CD-keys. Most developers will use the newer BNLS_CDKEY_EX flavor of the packet if they use it at all.

BNLS_LOGONCHALLENGE and BNLS_LOGONPROOF:

• These are used for logging into a Battle.net account using the NLS system. Do not use these with OLS.

BNLS_CREATEACCOUNT:

• This is used with SID_AUTH_CREATEACCOUNT as part of NLS. Do not use this with OLS.

BNLS_CHANGECHALLENGE and BNLS_CHANGEPROOF:

• These are used to change the password to a Battle.net account using the NLS system. Do not use these with OLS.

BNLS_UPGRADECHALLENGE and BNLS_UPGRADEPROOF:

• These are used to upgrade a legacy OLS-style account to the newer NLS-style account system. Battle.net discontinued this feature, so there's really no interest in implementing these except for compatibility reasons.

BNLS_HASHDATA:

• This is used to hash passwords using OLS.