Battle.net Authenticator Tool

---

🛑 NOT MAINTAINED / BROKEN BY BLIZZARD 🛑

This repository is functional ONLY as a local backup manager. Online features are dead.

💻 What Happened?

Blizzard recently modified their identity API endpoints and restricted authentication scopes. This change was implemented to prevent users from extracting their raw device secrets and forcing them to use the heavy, official Battle.net mobile app for 2FA.

This tool was built using completely legal, public API documentation without packet sniffing. However, because Blizzard has locked down these endpoints to restrict user choice, you can no longer attach new authenticators or retrieve secrets online using this script.

🚨 Read Before Opening an Issue:

• Will this be fixed? Only if a someone manages to legally map the new endpoints or payload schemas. Pull Requests are welcome.
• Are you locked out of your account? I have zero association with Blizzard and zero access to their backend. Do not open an issue. You must contact Blizzard Customer Support directly to have the authenticator detached from your account.
• Spam Policy: Any issue opened asking for a "fix," reporting an API connection failure, or asking for account help will be locked and deleted immediately.

---

🔍 Legacy Local Functions (What Still Works)

If you already ran this tool in the past and have your battlenet_authenticator_SERIAL.json backup file, the tool is 100% operational offline:

• Reconstruct TOTP: Generates your standard RFC 6238 TOTP keys (8 digits, 30s period) and outputs a QR code to import into Aegis, Bitwarden, 1Password, or Google Authenticator.
• Local Security: Encrypt or decrypt your local JSON backups using strong AES-256-GCM encryption (upgraded to 600k PBKDF2 iterations in v1.3.0).

---

🛠️ Offline Usage

If you are running the tool locally to regenerate keys from an existing backup:

pip install requests cryptography "qrcode[pil]"
python bnet_auth_tool.py

---

Version History

Version: 1.3.0

A Python-based command-line tool for managing Battle.net software authenticators. This tool allows you to:

• Attach a new software authenticator to your Battle.net account.
• Retrieve the secret details of an existing software authenticator using its Serial Number and Restore Code.
• Generate standard TOTP (Time-Based One-Time Password) configuration (Base32 secret, otpauth:// URL) and a QR code compatible with common authenticator apps (like Google Authenticator, Authy, Microsoft Authenticator, etc.).
• Optionally encrypt the saved authenticator details using strong AES-256-GCM encryption derived from a user-provided passphrase.
• Load previously saved authenticator details (plain or encrypted) to regenerate the TOTP URL and QR code.
• Encrypt previously saved plain-text authenticator files.
• Decrypt previously encrypted authenticator files (for viewing or saving as plain text).

Disclaimer: This tool interacts with your Battle.net account and handles sensitive security information (authenticator secrets). Use it responsibly and at your own risk. Ensure you understand the security implications and securely manage any generated files and passphrases. The author is not responsible for any damage or loss resulting from the use of this tool.

Features

• Attach New Authenticator: Guides through attaching a new virtual authenticator.
• Retrieve Existing Secret: Recovers the secret key if you have the Serial and Restore Code.
• Standard TOTP Output: Generates Base32 secrets and otpauth:// URLs compatible with RFC 6238 (SHA1, 8 Digits, 30s period for Battle.net).
• QR Code Generation: Creates .png QR codes for easy import into authenticator apps.
• Secure File Encryption (Optional): Uses AES-256-GCM with PBKDF2 (increased to 600k iterations in v1.3.0) for strong protection of saved secrets.
• File Management: Load, reconstruct, encrypt, and decrypt saved authenticator files (.json).
• Backward Compatibility: Can decrypt files encrypted with older versions (v1.2) that used fewer PBKDF2 iterations (100k).
• Region Support: Works with session tokens from various Battle.net regions (US, EU, KR, TW, CN detected).

Security Warning

• Backup Your Data: The .json file generated by this tool contains your authenticator's Serial, Restore Code, and the critical Device Secret. Losing this file (especially if unencrypted) and the Restore Code means you could lose access to your authenticator. Back up this file securely (e.g., encrypted external drive, password manager).
• Protect Your Passphrase: If you choose to encrypt the .json file, your passphrase is the only way to decrypt it. There is no recovery for a lost passphrase. Choose a strong, unique passphrase and store it securely.
• Secure QR Codes: The generated .png QR code also contains your secret key. Treat it as securely as the .json file. Delete it after successfully importing it into your authenticator app(s).
• Session Token Exposure: The process requires obtaining a temporary session token from your browser. Ensure you do this in a secure environment and log out afterwards if using a public computer.

Important Notice for Users Upgrading from v1.2

Version 1.3.0 introduces a significant improvement to the security of newly encrypted files by increasing the PBKDF2 iteration count. This makes brute-force attacks against the encryption passphrase much harder.

Compatibility:

• ✅ v1.3.0 CAN decrypt files encrypted by v1.2: The new version automatically detects if a file is missing the iteration count field and assumes the old count for decryption. Your old encrypted files will work fine with v1.3.0.
• ❌ v1.2 CANNOT decrypt files encrypted by v1.3.0: If you encrypt a file using v1.3.0 (either by attaching/retrieving and choosing encrypt, or using the "Encrypt existing" option), the older v1.2 script will not be able to decrypt it due to the mismatch in iteration counts.

Recommendation:

• Upgrade: All users should upgrade to v1.3.0 or later for the improved security and compatibility handling.
• (Optional) Re-encrypt: For maximum security benefit on your existing files, you can:
  1. Use v1.3.0 to decrypt your old .json file (using option 5 and saving to a new plain file).
  2. Use v1.3.0 to encrypt that newly saved plain file (using option 4). This will re-encrypt it with the stronger 600k iterations.
  3. Securely delete the intermediate plain text file.

Requirements

• Python 3.7+
• Required Python libraries (install via pip):
  • requests
  • cryptography
  • qrcode[pil] (This installs both qrcode and the Pillow imaging library)

Installation

Recommended: Download the pre-compiled executable from the Releases page. This avoids needing Python or manual library installation.

Manual (using Python):

1. Ensure Python 3.7+ and pip are installed and accessible from your command line.
2. Clone the repository or download the source code (.zip).

   git clone https://github.com/Nighthawk42/bnet_auth_tool.git
   cd bnet_auth_tool
   

3. Install the required libraries:

   pip install -r requirements.txt
   # Or: pip install requests cryptography "qrcode[pil]"
   

Usage

1. Open your terminal or command prompt.
2. Navigate to the directory where you placed the script or executable.
3. Run the tool:
   • If using the Python script:

     python bnet_auth_tool.py
     # or potentially: python3 bnet_auth_tool.py
     

   • If using the executable (Windows example):

     bnet_auth_tool.exe
     

4. The tool will display a menu with available actions:
   • Attach a new authenticator: Guides you through getting a session token and attaches a new virtual authenticator, saving the details.
   • Retrieve existing device secret: Guides you through getting a session token and uses your existing Serial/Restore code to retrieve the secret, saving the details.
   • Reconstruct TOTP from JSON: Loads a saved .json file (plain or encrypted, prompts for passphrase if needed) and displays the TOTP info / generates a QR code.
   • Encrypt existing plain JSON file(s): Finds unencrypted .json files in the directory, prompts you to select which ones to encrypt, and asks for a passphrase. Overwrites the original file.
   • Decrypt an encrypted JSON file: Prompts you to select an encrypted .json file, asks for the passphrase, and then offers to display the decrypted data or save it to a new plain-text .json file.
   • Exit: Closes the tool.
5. Follow the on-screen prompts for each action. Pay close attention to instructions for obtaining the session token and handling passphrases.

---

Output Files

• .json File: (battlenet_authenticator_SERIAL.json)
  • Contains the Serial Number, Restore Code, raw hexadecimal Device Secret, Base32 secret, otpauth:// URL, and a timestamp. (Encrypted files also contain salt, nonce, and iteration count).
  • This file is crucial for backup and recovery.
  • Can be saved as plain text or encrypted (recommended).
• .png File: (battlenet_authenticator_SERIAL.png or reconstructed_SERIAL.png)
  • A QR code image containing the otpauth:// URL.
  • Scan this with your authenticator app to add the key.
  • Securely delete after successful import.

Donations