Version 1.3.0

Version bump.

Rewritten for better clarity, improved encryption.

README.md

@@ -1,31 +1,112 @@
 # Battle.net Authenticator Tool
 
-A Python-based tool for managing Battle.net authenticators. This tool allows you to attach new authenticators, retrieve existing device secrets, and generate TOTP keys and QR codes for easy integration with authenticator apps.
+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 a new Battle.net authenticator to your account.
-- Retrieve existing device secrets using serial and restore codes.
-- Generate TOTP URLs and QR codes for use with TOTP-compatible authenticator apps.
+*   **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 libraries:
-  - `requests`
-  - `pillow`
-  - `qrcode`
+*   Python 3.7+
+*   Required Python libraries (install via pip):
+    *   `requests`
+    *   `cryptography`
+    *   `qrcode[pil]` (This installs both `qrcode` and the `Pillow` imaging library)
 
 ## Installation
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/Nighthawk42/bnet-authenticator-tool.git
-   cd battlenet-authenticator-tool
+**Recommended:** Download the pre-compiled executable from the [Releases page](https://github.com/Nighthawk42/bnet_auth_tool/releases/). This avoids needing Python or manual library installation.
 
-2. Run the script:
-   ```bash
-   py bnet_auth_tool.py`
+**Manual (using Python):**
 
-4. Follow the instructions from the console window.
-    
+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`).
+    ```bash
+    git clone https://github.com/Nighthawk42/bnet_auth_tool.git
+    cd bnet_auth_tool
+    ```
+3.  Install the required libraries:
+    ```bash
+    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:
+        ```bash
+        python bnet_auth_tool.py
+        # or potentially: python3 bnet_auth_tool.py
+        ```
+    *   If using the executable (Windows example):
+        ```bash
+        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.

requirements.txt

@@ -0,0 +1,4 @@
+cryptography
+qrcode
+Pillow
+requests