Overview
WhatsApp has evolved its backup encryption over the years, introducing three major formats: crypt12, crypt14, and crypt15. Each version introduced stronger encryption and additional security features. Understanding these formats is crucial for successful decryption and forensic analysis.Encryption Format Evolution
Timeline
- crypt12 (Legacy): AES-GCM with fixed key derivation
- crypt14 (Current): AES-GCM with key file (
keyfile required) - crypt15 (Latest): End-to-end encrypted with user passphrase
The tool supports all three formats with automatic format detection based on file extension and structure.
crypt12 Format (Legacy)
Overview
Status: Deprecated (used prior to 2018)Cipher: AES-256-GCM
Key Source: Extracted from WhatsApp APK or device memory
File Structure
Decryption Process
Implemented inCryptoManager.decrypt_file() at core/crypto_manager.py:143-150:
Key Characteristics
- Fixed offsets: IV and data start at predictable positions
- Compression: Data is zlib-compressed before encryption
- No key file: Key is derived from device-specific data
- Authentication: GCM tag ensures data integrity
crypt12 files can often be decrypted with a universal key extracted from the WhatsApp APK, as key derivation was less secure.
crypt14 Format (Current)
Overview
Status: Widely used (2018-present)Cipher: AES-256-GCM
Key Source: External
key file stored on device
File Structure
Common Offsets
The tool defines common offset patterns inCOMMON_OFFSETS at core/crypto_manager.py:24:
- IV start: Where the 16-byte nonce begins
- IV end: Where the nonce ends
- Data start: Where encrypted data begins
Key Derivation
crypt14 uses HMAC-based key derivation implemented atcore/crypto_manager.py:125-127:
- First HMAC:
HMAC-SHA256(key=\x00*32, message=raw_key_file_contents) - Second HMAC:
HMAC-SHA256(key=intermediate, message="backup encryption\x01") - Output: 256-bit AES key
Decryption Algorithm
Implemented atcore/crypto_manager.py:152-186:
- Try derived key with known offsets
- Try raw key with known offsets
- If failed, brute force scan offsets (lines 172-186)
Tag Position Variations
Some crypt14 files have:- 16-byte tag: Standard GCM tag at end
- 32-byte footer: 16-byte padding + 16-byte tag
ct[-32:-16] and ct[-16:].
Brute Force Offset Scanning
If known offsets fail, the tool scans for correct positions:Brute force scanning typically completes in 1-5 seconds and is triggered automatically when known offsets fail.
crypt15 Format (Latest)
Overview
Status: Newest format (2021+)Cipher: AES-256-GCM
Key Source: End-to-end encrypted with user-provided 64-digit passphrase
Key Differences
- User passphrase required: Cannot extract key from device alone
- Cloud backup encryption: Designed for encrypted cloud storage
- Stronger security: Key never stored on device in plaintext
Decryption Support
The tool treats crypt15 similarly to crypt14, attempting offset scanning and key derivation. However:- The
keyfile alone is insufficient - User must enter the backup passphrase (shown in WhatsApp settings)
- Key derivation may differ (evolving format)
Backup Passphrase Location
Users can find their 64-digit backup key in WhatsApp:- Settings → Chats → Chat Backup
- Tap End-to-end encrypted backup
- View or create 64-digit key
Cipher Modes: CBC vs GCM
AES-GCM (Used by Tool)
Mode: Galois/Counter ModeBenefits:
- Authentication: Built-in integrity checking via tag
- Parallelizable: Faster decryption
- No padding required: Works with any data length
AES-CBC (Legacy)
Mode: Cipher Block ChainingIssues:
- No authentication: Must use separate HMAC
- Padding required: PKCS7 padding
- Sequential: Cannot parallelize
WhatsApp migrated from CBC to GCM in early versions. All modern backups (crypt12+) use GCM.
Practical Decryption Examples
Example 1: crypt14 with Known Offset
Example 2: crypt12 Legacy
Example 3: Offset Scanning Fallback
Implementation Deep Dive
Main Decryption Function
Location:core/crypto_manager.py:129-192
Flow:
-
Validate input (line 130-135)
- Check file exists
- Unhexlify key
-
Detect format (line 140)
- Check if
.crypt12extension
- Check if
-
Try crypt12 decryption (lines 143-150)
- Fixed offsets
- Direct key usage
-
Try crypt14 decryption (lines 152-186)
- Known offsets with derived key
- Known offsets with raw key
- Brute force offset scan
-
Write output (lines 188-192)
- Write decrypted SQLite database
- Return success status
Error Handling
The tool uses try-except blocks extensively:Debugging Failed Decryption
Enable Verbose Logging
Modifycore/crypto_manager.py to add debug output:
Inspect File Header
- Magic bytes (often starts with specific patterns)
- Version indicators
- Offset hints
Verify Key Format
Key must be exactly 64 hexadecimal characters:Common Decryption Errors
”MAC check failed”
Cause: Wrong key or corrupted fileSolution:
- Verify key is correct
- Extract key again from device
- Check file integrity (not truncated)
“Error -3 while decompressing data”
Cause: Wrong offsets or incomplete decryptionSolution:
- Let tool scan offsets (takes longer)
- Try raw key if derived key fails
”File not found”
Cause: Incorrect path or permissionsSolution:
- Use absolute paths
- Check file permissions (
chmod 644 file.crypt14)
Security Considerations
Key Storage
Forensic Best Practices
- Work on copies: Never decrypt original evidence
- Hash verification: SHA-256 hash files before/after
- Chain of custody: Log all decryption operations
- Secure key handling: Use hardware tokens for key storage
Format Detection Algorithm
The tool uses a simple extension-based detection:- Magic byte detection (header inspection)
- Automatic version detection from file structure
- Support for crypt8-crypt11 formats
References
Implementation Files:core/crypto_manager.py:129-192- Main decryption logiccore/crypto_manager.py:24- Common offset definitionscore/crypto_manager.py:125-127- Key derivation function
Crypto.Cipher.AES- AES encryption (PyCryptodome)hashlib.sha256- SHA-256 hashinghmac- HMAC key derivationzlib- Data decompressionbinascii.unhexlify- Hex string to bytes conversion
