jackbentley / php-encrypted-streams

Encrypt or decrypt streaming data of unbounded sizes. Uses PSR-7 compatible streams.

PSR-7 Stream Encryption Decorators

PHP's built-in OpenSSL bindings provide a convenient means of encrypting and decrypting data. The interface provided by ext-openssl, however, only operates on strings, so decrypting a large ciphertext would require loading the entire ciphertext into memory and receiving a string containing the entirety of the decoded plaintext.

This package aims to allow the encryption and decryption of streams of arbitrary size. It supports streaming encryption and decryption using AES-CBC, AES-CTR, and AES-ECB.

Using AES-ECB is NOT RECOMMENDED for new systems. It is included to allow interoperability with older systems. Please consult Wikipedia for a discussion of the drawbacks of ECB.

Usage

Decorate an instance of Psr\Http\Message\StreamInterface with an encrypting decorator to incrementally encrypt the contents of the decorated stream as read is called on the decorating stream:

$cipherMethod = new Jsq\EncryptionStreams\Cbc(
    random_bytes(openssl_cipher_iv_length('aes-256-cbc'))
);
$key = ... // a symmetric encryption key 
// Create a PSR-7 stream for a very large file.
$plaintext = new GuzzleHttp\Psr7\LazyOpenStream('/path/to/a/massive/file', 'r+);
// Create an encrypting stream.
$ciphertext = new Jsq\EncryptionStreams\AesEncryptingStream(
    $plaintext,
    $key,
    $cipherMethod
);

$encryptedChunk = $ciphertext->read(1024 * 1024);

No encryption is performed until read is called on the encrypting stream.

To calculate the HMAC of a cipher text, wrap a decorated stream with an instance of HashingStream:

$hash = null;
$ciphertext = new Jsq\EncryptionStreams\AesEncryptingStream(
    $plaintext,
    $key,
    $cipherMethod
);
$hashingDecorator = new Jsq\EncryptionStreams\HashingStream(
    $ciphertext,
    $key,
    function ($calculatedHash) use (&$hash) {
        $hash = $calculatedHash;
    }
);

while (!$ciphertext->eof()) {
    $ciphertext->read(1024 * 1024);
}

assert('$hash === $hashingDecorator->getHash()');

When decrypting a cipher text, wrap the cipher text in a hasing decorator before passing it as an argument to the decrypting stream:

$key = 'secret key';
$iv = random_bytes(openssl_cipher_iv_length('aes-256-cbc'));
$plainText = 'Super secret text';
$cipherText = openssl_encrypt(
    $plainText,
    'aes-256-cbc',
    $key,
    OPENSSL_RAW_DATA
    $iv
);
$expectedHash = hash('sha256', $cipherText);

$hashingDecorator = new Jsq\EncryptingStreams\HashingStream(
    GuzzleHttp\Psr7\stream_for($cipherText),
    $key,
    function ($hash) use ($expectedHash) {
        if ($hash !== $expectedHash) {
            throw new DomainException('Cipher text mac does not match expected value!');
        }
    }
);

$decrypted = new Jsq\EncryptionStreams\AesEncryptingStream(
    $cipherText,
    $key,
    $cipherMethod
);
while (!$decrypted->eof()) {
    $decrypted->read(1024 * 1024);
}

As with the encrypting decorators, HashingStreams are lazy and will only hash the underlying stream as it is read. In the example above, no exception would be thrown until the entire cipher text had been read (and all but the last block deciphered).

HashingStreams are not seekable, so you will need to wrap on in a GuzzleHttp\Psr7\CachingStream to support random access.