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:

const {CipherSweet, EncryptedFile} = require('ciphersweet-js');

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

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

// Encrypting a file with CipherSweet
encFile.encryptFile(
    '/tmp/super-secret', 
    '/tmp/super-secret.enc'
).then(function() {
    console.log('File encryption complete');
});

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

Decryption is a congruent operation:

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

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:

(async function () {
    let password = 'correct horse battery staple';
    
    // Encrypting a file with CipherSweet
    await encFile.encryptFileWithPassword(
        '/tmp/super-secret',
        '/tmp/super-secret.enc',
        password
    );
    
    // Decrypting a file with CipherSweet
    if (await encFile.isFileEncrypted('/tmp/super-secret.enc')) {
        await encFile.decryptFileWithPassword(
            '/tmp/super-secret.enc',
            '/tmp/super-secret.dec',
            $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.