EncryptedFile

CipherSweet provides an EncryptedFile API that provides authenticated encryption, password-based encryption, and resistance against race condition attacks.

Using EncryptedFile in your Projects

First, instantiate the EncryptedFile class by passing your engine to the constructor, like so:

<?php
use ParagonIE\CipherSweet\CipherSweet;
use ParagonIE\CipherSweet\EncryptedFile;

/** @var CipherSweet $engine */
$encFile = new EncryptedFile($engine);

Now that you have an EncryptedFile object, you can use it to encrypt files on disk or PHP streams.

<?php
use ParagonIE\CipherSweet\EncryptedFile;
/** @var EncryptedFile $encFile */

// Encrypting a file with CipherSweet
$encFile->encryptFile(
    '/tmp/super-secret', 
    '/tmp/super-secret.enc'
);

// Encrypting a stream with CipherSweet
$input = \fopen('/tmp/super-secret', 'rb');
$output = \fopen('php://temp', 'wb');
$encFile->encryptStream($input, $output);

The above functions will use the key provider and backend from your CipherSweet object to encrypt each file.

Decryption is a congruent operation:

<?php
use ParagonIE\CipherSweet\EncryptedFile;
/** @var EncryptedFile $encFile */

// Decrypting a file with CipherSweet
if ($encFile->isFileEncrypted('/tmp/super-secret.enc')) {
    $encFile->decryptFile(
        '/tmp/super-secret.enc',
        '/tmp/super-secret.dec'
    );
}

// Decrypting a stream with CipherSweet
$input = \fopen('/tmp/super-secret.enc', 'rb');
$output = \fopen('php://temp', 'wb');
if ($encFile->isStreamEncrypted($input)) {
    $encFile->decryptStream($input, $output);
}

The isFileEncrypted() and isStreamEncrypted() methods return TRUE only if this file was encrypted with the same backend as the current engine.

If you'd rather encrypt each file with a password rather than a local key, you can use the *WithPassword() API instead:

<?php
use ParagonIE\CipherSweet\EncryptedFile;
/** @var EncryptedFile $encFile */

$password = 'correct horse battery staple';

// Encrypting a file with CipherSweet
$encFile->encryptFileWithPassword(
    '/tmp/super-secret',
    '/tmp/super-secret.enc',
    $password
);

// Encrypting a stream with CipherSweet
$input = \fopen('/tmp/super-secret', 'rb');
$output = \fopen('php://temp', 'wb');
$encFile->encryptStreamWithPassword($input, $output, $password);

// Decrypting a file with CipherSweet
if ($encFile->isFileEncrypted('/tmp/super-secret.enc')) {
    $encFile->decryptFileWithPassword(
        '/tmp/super-secret.enc',
        '/tmp/super-secret.dec',
        $password
    );
}

// Decrypting a stream with CipherSweet
$input = \fopen('/tmp/super-secret.enc', 'rb');
$output = \fopen('php://temp', 'wb');
if ($encFile->isStreamEncrypted($input)) {
    $encFile->decryptStreamWithPassword($input, $output, $password);
}

Please be aware that encrypting with a password does NOT use your local encryption key.

To learn more about how EncryptedFile was designed and implemented, please refer to the internal documentation.