PHPackages wizardloong/whatsapp-stream-encryption - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. wizardloong/whatsapp-stream-encryption ActiveLibrary[Security](/categories/security) wizardloong/whatsapp-stream-encryption ====================================== PSR-7 stream decorators for WhatsApp-style encryption and decryption v1(8mo ago)12MITPHPPHP >=8.1CI passing Since Aug 20Pushed 8mo agoCompare [ Source](https://github.com/wizardloong/whatsapp-stream-encryption)[ Packagist](https://packagist.org/packages/wizardloong/whatsapp-stream-encryption)[ RSS](/packages/wizardloong-whatsapp-stream-encryption/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (3)Versions (2)Used By (0) WhatsApp Media Encryption/Decryption PHP Library ================================================ [](#whatsapp-media-encryptiondecryption-php-library) Overview -------- [](#overview) This PHP library provides tools for encrypting and decrypting WhatsApp media files (images, audio, video) using the official WhatsApp algorithm. It supports streaming encryption/decryption, MAC validation, and sidecar generation for video integrity. - **Encryption**: AES-256-ECB with CBC-like chaining and PKCS#7 padding. - **Decryption**: Validates MAC, removes padding, and restores original media. - **Sidecar**: Generates chunked MACs for video files (used by WhatsApp for integrity checks). - **Streaming**: Works with PSR-7 streams for efficient memory usage. Features -------- [](#features) - Compatible with WhatsApp's official media encryption format - Handles large files efficiently (streaming, chunked processing) - Validates MAC for data integrity - Generates sidecar MACs for video - Custom exceptions for robust error handling - Fully tested with PHPUnit and sample files Installation ------------ [](#installation) Clone the repository and install dependencies: ``` git clone https://github.com/wizardloong/whatsapp-stream-encryption cd whatsapp-stream-encryption composer install ``` Usage ----- [](#usage) First, install the package via Composer in your project: ``` composer require wizardloong/whatsapp-stream-encryption ``` Then use it in your code: ### Encrypting Media [](#encrypting-media) ``` require 'vendor/autoload.php'; use Wizardloong\WhatsAppStreamEncryption\WhatsAppEncryptingStream; use Wizardloong\WhatsAppStreamEncryption\MediaType; use GuzzleHttp\Psr7\Utils; $mediaKey = random_bytes(32); // Or use WhatsApp-provided key $inputStream = Utils::streamFor(fopen('input.jpg', 'rb')); $encrypting = new WhatsAppEncryptingStream($inputStream, MediaType::IMAGE, $mediaKey); $outputStream = fopen('output.encrypted', 'wb'); while (!$encrypting->eof()) { fwrite($outputStream, $encrypting->read(8192)); } fclose($outputStream); ``` ### Decrypting Media [](#decrypting-media) ``` require 'vendor/autoload.php'; use Wizardloong\WhatsAppStreamEncryption\WhatsAppDecryptingStream; use Wizardloong\WhatsAppStreamEncryption\MediaType; use GuzzleHttp\Psr7\Utils; $mediaKey = file_get_contents('IMAGE.key'); $encryptedStream = Utils::streamFor(fopen('output.encrypted', 'rb')); $decrypting = new WhatsAppDecryptingStream($encryptedStream, MediaType::IMAGE, mediaKey); $outputStream = fopen('output.decrypted.jpg', 'wb'); while (!$decrypting->eof()) { fwrite($outputStream, $decrypting->read(8192)); } fclose($outputStream); ``` ### Video Sidecar Generation [](#video-sidecar-generation) ``` require 'vendor/autoload.php'; use Wizardloong\WhatsAppStreamEncryption\WhatsAppEncryptingStream; use Wizardloong\WhatsAppStreamEncryption\MediaType; use GuzzleHttp\Psr7\Utils; $mediaKey = file_get_contents('VIDEO.key'); $inputStream = Utils::streamFor(fopen('input.mp4', 'rb')); $encrypting = new WhatsAppEncryptingStream($inputStream, MediaType::VIDEO, $mediaKey, true); $outputStream = fopen('output.encrypted', 'wb'); while (!$encrypting->eof()) { fwrite($outputStream, $encrypting->read(16384)); } fclose($outputStream); $sidecar = $encrypting->getSidecar(); file_put_contents('output.sidecar', $sidecar); ``` Running Tests ------------- [](#running-tests) Tests use PHPUnit and sample files in the `samples/` directory. ``` make test # or vendor/bin/phpunit --testdox ``` Specifications -------------- [](#specifications) - **Key Expansion**: Uses HKDF-SHA256 to derive IV, cipherKey, and macKey from mediaKey and mediaType. - **Encryption**: AES-256-ECB, CBC-like chaining (XOR with previous block), PKCS#7 padding. - **MAC**: HMAC-SHA256 over IV + ciphertext, first 10 bytes appended as trailer. - **Sidecar (video)**: HMAC-SHA256 over each 64KB chunk + 16-byte overlap, first 10 bytes per chunk. - **Decryption**: Validates MAC, removes PKCS#7 padding, restores original data. - **Exceptions**: Throws custom exceptions for encryption/decryption errors. File Structure -------------- [](#file-structure) - `src/WhatsAppEncryptingStream.php` — Streaming encryption implementation - `src/WhatsAppDecryptingStream.php` — Streaming decryption implementation - `src/KeyExpander.php` — Key derivation logic - `src/MediaType.php` — Media type enum - `src/Exceptions/EncryptionException.php` — Encryption error class - `src/Exceptions/DecryptionException.php` — Decryption error class - `tests/WhatsAppSamplesTest.php` — Integration tests - `samples/` — Sample media, keys, and expected outputs Error Handling -------------- [](#error-handling) - Throws `EncryptionException` for encryption failures (OpenSSL, padding, etc.) - Throws `DecryptionException` for decryption failures (MAC, padding, etc.) Notes ----- [](#notes) - Always use chunked reading/writing for large files to avoid memory issues. - MediaKey must be 32 bytes (random or WhatsApp-provided). - Sidecar is only needed for video integrity checks. License ------- [](#license) MIT Authors ------- [](#authors) - Victor Miroliubov Contributing ------------ [](#contributing) Pull requests and issues are welcome! ### Health Score 31 — LowBetter than 68% of packages Maintenance62 Regular maintenance activity Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 262d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/9bbe2f1b64c4645f1ceedc7a10a9a43c2779680bfaa43e04b8c29aca3657d8c6?d=identicon)[wizardloong](/maintainers/wizardloong) --- Top Contributors [![wizardloong](https://avatars.githubusercontent.com/u/24416090?v=4)](https://github.com/wizardloong "wizardloong (6 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/wizardloong-whatsapp-stream-encryption/health.svg) ``` [![Health](https://phpackages.com/badges/wizardloong-whatsapp-stream-encryption/health.svg)](https://phpackages.com/packages/wizardloong-whatsapp-stream-encryption) ``` ### Alternatives [shieldon/shieldon Web application firewall for PHP. 87328.2k1](/packages/shieldon-shieldon)[selective/samesite-cookie Secure your site with SameSite cookies 10144.0k](/packages/selective-samesite-cookie)[swop/github-webhook Library which deals with incoming GitHub web hooks requests (signature validation & payload parsing) 1119.5k4](/packages/swop-github-webhook) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)