README

This package provides PSR-7 compatible stream decorators that allow incremental encryption and decryption of streams of arbitrary size.
It also supports creating sidecar streams.

Installation

Install the package via Composer:

composer require pikulsky/whatsapp-streams

Usage

Encrypting a stream

Wrap any StreamInterface with WhatsAppEncryptingStream to encrypt data as it's being read:

use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$plainStream = Utils::streamFor(fopen('input.file', 'r'));

$cipher = new WhatsAppAudioCipher($key);
$encryptingStream = new WhatsAppEncryptingStream($plainStream, $cipher);

$outputStream = Utils::streamFor(fopen('encrypted.file', 'w'));
Utils::copyToStream($encryptingStream, $outputStream);

No encryption is performed until you read from the encrypting stream.

Decrypting a stream

To decrypt, wrap the encrypted stream with WhatsAppDecryptingStream:

use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$encryptedStream = Utils::streamFor(fopen('encrypted.file', 'r'));

$cipher = new WhatsAppAudioCipher($key);
$decryptingStream = new WhatsAppDecryptingStream($encryptedStream, $cipher);

$outputStream = Utils::streamFor(fopen('decrypted.file', 'w'));
Utils::copyToStream($decryptingStream, $outputStream);

Sidecar

A sidecar stream is used to generate additional authentication data alongside encrypted media. To produce a sidecar, wrap the encrypting stream with WhatsAppSidecarStream and pass a writable stream for the sidecar output:

use GuzzleHttp\Psr7\Utils;

$key = 'some-secret-key-here-32-bytes-long';
$plainStream = Utils::streamFor(fopen('input.file', 'r'));

$cipher = new WhatsAppVideoCipher($key);
$encryptingStream = new WhatsAppEncryptingStream($plainStream, $cipher);

$sidecarStream = Utils::streamFor('');
$sidecarDecorator = new WhatsAppSidecarStream($encryptingStream, $cipher, $sidecarStream);

$outputStream = Utils::streamFor(fopen('encrypted.file', 'w'));
Utils::copyToStream($sidecarDecorator, $outputStream);

$sidecarContent = (string) $sidecarStream;

Cipher & Key Types

A cipher is required for encryption and decryption. The library provides specialized key types and ciphers for different media types.

Available Key Types

The library supports three media-specific key types:

AudioKey - for audio
ImageKey - for image
VideoKey - for video

Available Ciphers

Corresponding to the key types, the library provides specialized cipher implementations:

WhatsAppAudioCipher - handles encryption/decryption of audio
WhatsAppImageCipher - handles encryption/decryption of image
WhatsAppVideoCipher - handles encryption/decryption of vidoe

Usage Examples

Recommended (media-specific cipher):

$key = 'some-secret-key-here-32-bytes-long';

// For audio
$audioCipher = new WhatsAppAudioCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $audioCipher);

// For image
$imageCipher = new WhatsAppImageCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $imageCipher);

// For video
$videoCipher = new WhatsAppVideoCipher($key);
$encrypted = new WhatsAppEncryptingStream($original, $videoCipher);

Alternative (explicit key + generic cipher):

$key = 'some-secret-key-here-32-bytes-long';

// Using specific key types with generic cipher
$audioKey = new AudioKey($key);
$audioCipher = new WhatsAppCipher($audioKey);
$encrypted = new WhatsAppEncryptingStream($original, $audioCipher);

$imageKey = new ImageKey($key);
$imageCipher = new WhatsAppCipher($imageKey);
$encrypted = new WhatsAppEncryptingStream($original, $imageCipher);

$videoKey = new VideoKey($key);
$videoCipher = new WhatsAppCipher($videoKey);
$encrypted = new WhatsAppEncryptingStream($original, $videoCipher);

Dependecies

PHP 8.2
psr/http-message - PSR-7 stream interface
guzzlehttp/psr7 - PSR-7 stream utilities
jsq/psr7-stream-encryption - stream decorators for encryption, decryption and hashing

Note: the library jsq/psr7-stream-encryption is forked to pikulsky/php-encrypted-streams to add support for PHP 8.2 and improve HashingStream to pre-initialize the hash context with IV.

How it works

WhatsAppEncryptingStream uses decorators from jsq/psr7-stream-encryption library:

AesEncryptingStream for encryption
HashingStream - for generating the integrity hash of the encrypted data

WhatsAppDecryptingStream uses WhatsAppFinalizeStream decorator to split the encrypted data into the original data and the integrity hash, and also it uses decorators from jsq/psr7-stream-encryption library:

AesDecryptingStream for decryption
HashingStream - for validating the integrity of the decrypted data

pikulsky / whatsapp-streams

Maintainers

Details