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

01171[1 PRs](https://github.com/Vimpil/whatsapp-media-crypto/pulls)PHP

Since Feb 8Pushed 6mo 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 2w ago

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

21

—

LowBetter than 17% of packages

Maintenance47

Moderate activity, may be stable

Popularity13

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity13

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)
```

###  Alternatives

[jordanmiguel/laravel-popular

A Laravel package to track popularity of entries(by Models) in a website at a certain time.

6410.0k1](/packages/jordanmiguel-laravel-popular)[czdb/searcher

A PHP library for efficient IP geolocation using compact database formats.

295.8k1](/packages/czdb-searcher)[neysi/directprint

Easy and direct file print from PHP

198.8k](/packages/neysi-directprint)[ip2location/ip2location-cakephp

Lookup for visitor's IP information, such as country, region, city, coordinates, zip code, time zone, ISP, domain name, connection type, area code, weather, MCC, MNC, mobile brand name, elevation and usage type.

224.7k](/packages/ip2location-ip2location-cakephp)[maximaster/tools.finder

Библиотека, облегчающая поиск идентификаторов разных сущностей для 1С-Битрикс

108.6k](/packages/maximaster-toolsfinder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)