Step 2: Obtaining the Encryption Key
Relevant source files
The following files were used as context for generating this wiki page:
The project's documentation and source code do not provide a method for obtaining the WhatsApp encryption key. Instead, the system assumes the user has already acquired this 64-character hexadecimal key and provides it as a prerequisite for Step 1: Unlock Your Encrypted Backups. The key is essential for decrypting the .crypt15 database files.
The official "Step 2" in the project's guide refers to a different process: obtaining the chat list by exporting it from WhatsApp Web. This generates a model-storage-chat.json file, which is required alongside the decrypted database for the analysis application to function correctly. This page details both the usage of the pre-obtained encryption key and the process for generating the chat list file.
Sources: README.md:19, README.md:52-60, chatsExporter/whatsapp_db_android_exporter.py:4-5
Using the Pre-Obtained Encryption Key
The decryption process, outlined as "Step 1" in the project's README.md, relies on the whatsapp_db_android_exporter.py script. This script uses the 64-character encryption key to convert encrypted .crypt15 backup files into a readable SQLite database (.db).
Sources: README.md:38-50, chatsExporter/whatsapp_db_android_exporter.py
Configuration
The encryption key must be placed in a .env file within the chatsExporter/ directory. The script loads this configuration at runtime.
| Variable | Description | Example Value |
|---|---|---|
ENCRYPTION_KEY | The 64-character WhatsApp backup encryption key. Separators are ignored. | 1234abcd...ef56 |
TARGET_DIR | The directory path containing the .crypt15 backup files. | ./ or C:\Users\User\Documents\WhatsAppBackups |
Sources: README.md:42-45, chatsExporter/whatsapp_db_android_exporter.py:4-6, chatsExporter/whatsapp_db_android_exporter.py:99-104
Key Validation and Processing Flow
Before use, the script validates the provided key. The overall process from key input to database decryption is illustrated below.
This diagram shows the workflow of the whatsapp_db_android_exporter.py script.
The validate_hex_key function is responsible for ensuring the key is in the correct format.
# chatsExporter/whatsapp_db_android_exporter.py:53-60
def validate_hex_key(hex_input: str) -> str:
trimmed = re.sub(r"[^0-9a-fA-F]", "", hex_input or "")
if not trimmed:
raise ValueError("Missing encryption key.")
if len(trimmed) != 64:
raise ValueError("Encryption key must be 64 hexadecimal characters after trimming.")
return trimmed.lower()
Sources: chatsExporter/whatsapp_db_android_exporter.py:53-60
Obtaining the Chat List (Project Step 2)
The project's documented "Step 2" is to generate a model-storage-chat.json file. This file contains metadata about your chats, such as chat names and IDs, which are necessary for the web application to display conversations correctly.
Sources: README.md:52-60, web/src/Pages/SearchSQLite/components/UploadStep.jsx:40-43
Process Overview
The process involves executing a JavaScript snippet, dumbWAChats.js, in the browser's developer console while on the WhatsApp Web page.
- Open
https://web.whatsapp.comand wait for chats to load. - Open Developer Tools (
F12). - Navigate to
Sources->Snippets. - Create a new snippet and paste the contents of
dumbWAChats.js. - Run the snippet.
- The browser will download
model-storage-chat.json.
Sources: README.md:53-60
dumbWAChats.js Script Analysis
The script interacts with the browser's IndexedDB, where WhatsApp Web stores its data.
This sequence diagram illustrates how dumbWAChats.js extracts chat data from the browser.
Sources: chatsExporter/dumbWAChats.js
The key functions in the script are:
| Function | Description |
|---|---|
exportStore | Main function that orchestrates opening the DB, getting data, and downloading. |
openDB | Opens a connection to the specified IndexedDB database (model-storage). |
getAllFromStore | Retrieves all objects from a given object store (chat) within the database. |
downloadJSON | Converts the data array to a JSON blob and triggers a browser download. |
Sources: chatsExporter/dumbWAChats.js:1-27
Usage in the Web Application
The downloaded model-storage-chat.json and the decrypted msgstore.db are the two files required by the web application. The user uploads them in the first step of the analysis UI. The fileService.js then parses the JSON file to create a list of chats for filtering and display.
Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx:13-50, web/src/Pages/SearchSQLite/index.jsx:61-70, web/src/Pages/SearchSQLite/services/fileService.js:40-55
Conclusion
While the process of obtaining the 64-character encryption key is external to this project, the chatsExporter module provides the necessary validation and tooling to use it effectively for decrypting WhatsApp backups. The subsequent step, which involves generating a model-storage-chat.json via the dumbWAChats.js script, is a well-defined process that gathers the essential chat metadata required for the final analysis phase in the web application. Both the decrypted database and the chat list are critical inputs for the system.