PHPackages vimpil/whatsapp-media-crypto - 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. [Utility & Helpers](/categories/utility) 4. / 5. vimpil/whatsapp-media-crypto ActiveLibrary[Utility & Helpers](/categories/utility) vimpil/whatsapp-media-crypto ============================ PSR-7 stream decorators for WhatsApp media encryption/decryption 01071[1 PRs](https://github.com/Vimpil/whatsapp-media-crypto/pulls)PHP Since Feb 8Pushed 4mo agoCompare [ Source](https://github.com/Vimpil/whatsapp-media-crypto)[ Packagist](https://packagist.org/packages/vimpil/whatsapp-media-crypto)[ RSS](/packages/vimpil-whatsapp-media-crypto/feed)WikiDiscussions master Synced yesterday READMEChangelogDependenciesVersions (1)Used By (0) WhatsApp Media Crypto ===================== [](#whatsapp-media-crypto) A library for encrypting and decrypting media files using WhatsApp algorithms. Implements PSR-7 compatible stream decorators. Requirements ------------ [](#requirements) - PHP 7.4+ - OpenSSL extension - Composer Installation ------------ [](#installation) ``` composer require vimpil/whatsapp-media-crypto ``` Main Features ------------- [](#main-features) - PSR-7 compatible stream decorators - Support for various media types (images, video, audio, documents) - Streaming processing of large files - Built-in sidecar generation for video and audio streaming - Strict typing and complete documentation - 100% test coverage - Refactored `StreamFactory` with modular validation methods - Enhanced maintainability with detailed comments in core classes Project Structure ----------------- [](#project-structure) ``` src/ ├── Stream/ │ ├── AbstractCryptoStream.php # Base class for cryptographic streams │ ├── EncryptingStream.php # Encryption implementation │ └── DecryptingStream.php # Decryption implementation ├── HKDF.php # HKDF implementation ├── MediaKey.php # Media key handling └── StreamFactory.php # Stream factory with modular validation ``` Usage Examples -------------- [](#usage-examples) ### Image Encryption [](#image-encryption) ``` use WhatsAppMedia\StreamFactory; use GuzzleHttp\Psr7\Utils; $source = Utils::streamFor(fopen('image.jpg', 'rb')); $mediaKey = file_get_contents('image.key'); $encryptedStream = StreamFactory::createEncryptingStream( $source, $mediaKey, 'IMAGE' ); ``` ### Video/Audio Encryption with Sidecar Generation [](#videoaudio-encryption-with-sidecar-generation) ``` $source = Utils::streamFor(fopen('video.mp4', 'rb')); $mediaKey = file_get_contents('video.key'); $encryptedStream = StreamFactory::createEncryptingStream( $source, $mediaKey, 'VIDEO', true // enable sidecar generation ); // Drain the encrypted stream first so that the sidecar is fully generated while (!$encryptedStream->eof()) { $encryptedStream->read(8192); } // Get the sidecar after encryption $sidecar = $encryptedStream->getSidecar(); ``` ### File Decryption [](#file-decryption) ``` $encrypted = Utils::streamFor(fopen('encrypted_file', 'rb')); $mediaKey = file_get_contents('file.key'); $decryptedStream = StreamFactory::createDecryptingStream( $encrypted, $mediaKey, 'VIDEO' // or 'AUDIO', 'IMAGE', 'DOCUMENT' ); ``` Supported Media Types --------------------- [](#supported-media-types) TypeDescriptionApplication InfoSidecar SupportIMAGEImagesWhatsApp Image KeysNoVIDEOVideoWhatsApp Video KeysYesAUDIOAudioWhatsApp Audio KeysYesDOCUMENTDocumentsWhatsApp Document KeysNoReady-to-Use Examples --------------------- [](#ready-to-use-examples) The `examples/` directory contains ready-to-use scripts: ### Encryption [](#encryption) - `encrypt_image.php` - image encryption - `encrypt_video.php` - video encryption - `encrypt_audio.php` - audio encryption - `encrypt_document.php` - document encryption - `encrypt_video_streaming.php` - video encryption with sidecar - `encrypt_audio_streaming.php` - audio encryption with sidecar ### Decryption [](#decryption) - `decrypt_image.php` - image decryption - `decrypt_video.php` - video decryption - `decrypt_audio.php` - audio decryption - `decrypt_document.php` - document decryption All examples include: - File existence checks - Output directory creation - Error handling - File size information Implementation Details ---------------------- [](#implementation-details) ### Encryption [](#encryption-1) 1. Generate or use existing mediaKey (32 bytes) 2. Expand key using HKDF with SHA-256 and type-specific application info 3. Split into components: - iv: first 16 bytes - cipherKey: next 32 bytes - macKey: next 32 bytes - refKey: remaining 32 bytes (not used) 4. AES-CBC encryption using cipherKey and iv 5. HMAC generation using macKey ### Sidecar Generation (for video and audio) [](#sidecar-generation-for-video-and-audio) - Chunk size: 64KB - Overlap: 16 bytes - HMAC SHA-256 for each chunk, truncated to 10 bytes - On-the-fly generation without additional reads from source stream > Note: The 10-byte MAC truncation is WhatsApp-specific and is not an AEAD construction. It is implemented here for protocol compatibility and should not be reused as a generic cryptographic design. Testing ------- [](#testing) ``` composer install vendor/bin/phpunit ``` ### Test Coverage [](#test-coverage) Tests cover all requirements: 1. Basic functionality: - Encryption/decryption for all media types - Correct handling of various file sizes - Verification against reference files 2. Sidecar generation (bonus task): - Generation for video and audio files - Verification against reference sidecars - Format and size validation 3. Edge cases: - Invalid MAC verification - Empty stream handling - Key length validation - Unsupported media type checks Security -------- [](#security) - Input data validation - MAC verification for each chunk - Secure cryptographic primitive handling - Proper error handling - Data integrity verification License ------- [](#license) MIT License ### Health Score 22 — LowBetter than 21% of packages Maintenance50 Moderate activity, may be stable Popularity14 Limited adoption so far Community9 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 93.8% 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. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/10165263?v=4)[Kirill](/maintainers/Vimpil)[@Vimpil](https://github.com/Vimpil) --- Top Contributors [![vimpilteam](https://avatars.githubusercontent.com/u/110760529?v=4)](https://github.com/vimpilteam "vimpilteam (15 commits)")[![vimpil04](https://avatars.githubusercontent.com/u/16267827?v=4)](https://github.com/vimpil04 "vimpil04 (1 commits)") ### Embed Badge ![Health badge](/badges/vimpil-whatsapp-media-crypto/health.svg) ``` [![Health](https://phpackages.com/badges/vimpil-whatsapp-media-crypto/health.svg)](https://phpackages.com/packages/vimpil-whatsapp-media-crypto) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)