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.
- 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
.pngQR 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).
- Backup Your Data: The
.jsonfile 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
.jsonfile, 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
.pngQR code also contains your secret key. Treat it as securely as the.jsonfile. 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.
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:
- Use v1.3.0 to decrypt your old
.jsonfile (using option 5 and saving to a new plain file). - Use v1.3.0 to encrypt that newly saved plain file (using option 4). This will re-encrypt it with the stronger 600k iterations.
- Securely delete the intermediate plain text file.
- Use v1.3.0 to decrypt your old
- Python 3.7+
- Required Python libraries (install via pip):
requestscryptographyqrcode[pil](This installs bothqrcodeand thePillowimaging library)
Recommended: Download the pre-compiled executable from the Releases page. This avoids needing Python or manual library installation.
Manual (using Python):
- Ensure Python 3.7+ and
pipare installed and accessible from your command line. - Clone the repository or download the source code (
.zip).git clone https://github.com/Nighthawk42/bnet_auth_tool.git cd bnet_auth_tool - Install the required libraries:
pip install -r requirements.txt # Or: pip install requests cryptography "qrcode[pil]"
- Open your terminal or command prompt.
- Navigate to the directory where you placed the script or executable.
- 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
- If using the Python script:
- 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
.jsonfile (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
.jsonfiles 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
.jsonfile, asks for the passphrase, and then offers to display the decrypted data or save it to a new plain-text.jsonfile. - Exit: Closes the tool.
- Follow the on-screen prompts for each action. Pay close attention to instructions for obtaining the session token and handling passphrases.
.jsonFile: (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).
- Contains the Serial Number, Restore Code, raw hexadecimal Device Secret, Base32 secret,
.pngFile: (battlenet_authenticator_SERIAL.pngorreconstructed_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.
- A QR code image containing the