Forem: Thomas Pegler

File Encryption in Rust

Thomas Pegler — Mon, 06 May 2024 06:00:00 +0000

Back for another installment of how to maybe encrypt stuff using various languages, in this instance we're using Rust.

I still don't use Rust in my day-job, so I don't get a lot of time to toy with it at the minute and was very distracted. This weekend I finally managed to get back to it and have been working on a password manager CLI (another post will be coming later) which got me looking at how to handle file encryption, which is something I've not found too many useful posts on. So I decided to smash my face against the wall that is figuring out how to handle potentially large file encryption.

As ever, I am not a cryptographer so take this with a grain of salt and if I'm wrong, please let me know!

TL;DR

Use the below code and it should Just Work ^TM

cargo add orion
cargo add rand_core --features=getrandom

use std::fs::{File, remove_file};
use std::io::{Read, Write};

use orion::hazardous::{
    aead::xchacha20poly1305::{seal, open, Nonce, SecretKey},
    mac::poly1305::POLY1305_OUTSIZE,
    stream::xchacha20::XCHACHA_NONCESIZE,
};

use orion::hazardous::stream::chacha20::CHACHA_KEYSIZE;
use orion::kdf::{derive_key, Password, Salt};
use rand_core::{OsRng, RngCore};

fn get_random(dest: &mut [u8]) {
    RngCore::fill_bytes(&mut OsRng, dest);
}

fn nonce() -> Vec<u8> {
    let mut randoms: [u8; 24] = [0; 24];
    get_random(&mut randoms);
    return randoms.to_vec();
}

fn auth_tag() -> Vec<u8> {
    let mut randoms: [u8; 32] = [0; 32];
    get_random(&mut randoms);
    return randoms.to_vec();
}

fn simple_split_encrypted(cipher_text: &[u8]) -> (Vec<u8>, Vec<u8>) {
    return (
        cipher_text[..CHACHA_KEYSIZE].to_vec(),
        cipher_text[CHACHA_KEYSIZE..].to_vec(),
        )
}

fn create_key(password: String, nonce: Vec<u8>) -> SecretKey {
    let password = Password::from_slice(password.as_bytes()).unwrap();
    let salt = Salt::from_slice(nonce.as_slice()).unwrap();
    let kdf_key = derive_key(&password, &salt, 15, 1024, CHACHA_KEYSIZE as u32).unwrap();
    let key = SecretKey::from_slice(kdf_key.unprotected_as_bytes()).unwrap();
    return key;
}

fn encrypt_core(
    dist: &mut File,
    contents: Vec<u8>,
    key: &SecretKey,
    nonce: Nonce,
) {
    let ad = auth_tag();
    let output_len = match contents.len().checked_add(POLY1305_OUTSIZE + ad.len()) {
        Some(min_output_len) => min_output_len,
        None => panic!("Plaintext is too long"),
    };

    let mut output = vec![0u8; output_len];
    output[..CHACHA_KEYSIZE].copy_from_slice(ad.as_ref());
    seal(&key, &nonce, contents.as_slice(), Some(ad.clone().as_slice()), &mut output[CHACHA_KEYSIZE..]).unwrap();
    dist.write(&output.as_slice()).unwrap();
}

fn decrypt_core(
    dist: &mut File,
    contents: Vec<u8>,
    key: &SecretKey,
    nonce: Nonce
) {
    let split = simple_split_encrypted(contents.as_slice());
    let mut output = vec![0u8; split.1.len() - POLY1305_OUTSIZE];

    open(&key, &nonce, split.1.as_slice(), Some(split.0.as_slice()), &mut output).unwrap();
    dist.write(&output.as_slice()).unwrap();
}


const CHUNK_SIZE: usize = 128; // The size of the chunks you wish to split the stream into.

pub fn encrypt_large_file(
    file_path: &str,
    output_path: &str,
    password: String
) -> Result<(), orion::errors::UnknownCryptoError> {
    let mut source_file = File::open(file_path).expect("Failed to open input file");
    let mut dist = File::create(output_path).expect("Failed to create output file");

    let mut src = Vec::new();
    source_file.read_to_end(&mut src).expect("Failed to read input file");

    let nonce = nonce();

    dist.write(nonce.as_slice()).unwrap();
    let key = create_key(password, nonce.clone());
    let nonce = Nonce::from_slice(nonce.as_slice()).unwrap();

    for (n_chunk, src_chunk) in src.chunks(CHUNK_SIZE).enumerate() {
        encrypt_core(&mut dist, src_chunk.to_vec(), &key, nonce)
    }

    Ok(())
}

pub fn decrypt_large_file(
    file_path: &str, 
    output_path: &str,
    password: String
) -> Result<(), orion::errors::UnknownCryptoError> {
    let mut input_file = File::open(file_path).expect("Failed to open input file");
    let mut output_file = File::create(output_path).expect("Failed to create output file");

    let mut src: Vec<u8> = Vec::new();
    input_file.read_to_end(&mut src).expect("Failed to read input file");

    let nonce = src[..XCHACHA_NONCESIZE].to_vec();

    src = src[XCHACHA_NONCESIZE..].to_vec();

    let key = create_key(password, nonce.clone());
    let nonce = Nonce::from_slice(nonce.as_slice()).unwrap();

    for (n_chunk, src_chunk) in src.chunks(CHUNK_SIZE + CHACHA_KEYSIZE + POLY1305_OUTSIZE).enumerate() {
        decrypt_core(&mut output_file, src_chunk.to_vec(), &key, nonce);
    }

    Ok(())
}

Needed crates

Let's start with what crates we'll be using. For the actual encryption we'll be using the orion crate as it allows us to use XChaCha20. Next we'll use rand_core for RNG.

use orion::hazardous::{
    aead::xchacha20poly1305::{seal, open, Nonce, SecretKey},
    mac::poly1305::POLY1305_OUTSIZE,
    stream::xchacha20::XCHACHA_NONCESIZE,
};

use orion::hazardous::stream::chacha20::CHACHA_KEYSIZE;
use orion::kdf::{derive_key, Password, Salt};
use rand_core::{OsRng, RngCore};

In order to properly handle the encryption process we'll need a few helper functions.

Helpers

We need to be able to split the encrypted data into the key and the actual encrypted data:

fn split_encrypted(cipher_text: &[u8]) -> (Vec<u8>, Vec<u8>) {
    return (
        cipher_text[..CHACHA_KEYSIZE].to_vec(),
        cipher_text[CHACHA_KEYSIZE..].to_vec(),
        )
}

We also need to have a random nonce and a random authentication tag:

fn get_random(dest: &mut [u8]) {
    RngCore::fill_bytes(&mut OsRng, dest);
}

fn nonce() -> Vec<u8> {
    let mut randoms: [u8; 24] = [0; 24];
    get_random(&mut randoms);
    return randoms.to_vec();
}

fn auth_tag() -> Vec<u8> {
    let mut randoms: [u8; 32] = [0; 32];
    get_random(&mut randoms);
    return randoms.to_vec();
}

The last helper we need is to actually generate the secret key. Something I've overlooked in the past (much to my horror and dismay) is the fact you really need to use a KDF (Key Derivation Function) in order to get a good, secure key.

fn create_key(password: String, nonce: Vec<u8>) -> SecretKey{
    let password = Password::from_slice(password.as_bytes()).unwrap();
    let salt = Salt::from_slice(nonce.as_slice()).unwrap();
    let kdf_key = derive_key(&password, &salt, 15, 1024, CHACHA_KEYSIZE as u32).unwrap();
    let key = SecretKey::from_slice(kdf_key.unprotected_as_bytes()).unwrap();
    return key;
}

Now we're ready to start encrypting and decrypting files! I wanted to create some separate functions for the actual encryption and decryption since we want to be looping over chunks and having these inside the loops makes it harder to read.

note: we create an auth_tag for every chunk and that is important. The AD doesn't need to be secure but it does need to be unique per chunk. Technically the nonce should also be unique per chunk (the name being Number used ONCE) but that would add significant size and complexity so I opted not to

fn encrypt_core(
    dist: &mut File,
    contents: Vec<u8>,
    key: &SecretKey,
    nonce: Nonce,
) {
    let ad = auth_tag();
    let output_len = match contents.len().checked_add(POLY1305_OUTSIZE + ad.len()) {
        Some(min_output_len ) => min_output_len,
        None => panic!("Plaintext is too long"),
    };

    let mut output = vec![0u8; output_len];
    output[..CHACHA_KEYSIZE].copy_from_slice(ad.as_ref());
    seal(&key, &nonce, contents.as_slice(), Some(ad.clone().as_slice()), &mut output[CHACHA_KEYSIZE..]).unwrap();
    dist.write(&output.as_slice()).unwrap();
}

fn decrypt_core(
    dist: &mut File,
    contents: Vec<u8>,
    key: &SecretKey,
    nonce: Nonce
) {
    let split = simple_split_encrypted(contents.as_slice());
    let mut output = vec![0u8; split.1.len() - POLY1305_OUTSIZE];

    open(&key, &nonce, split.1.as_slice(), Some(split.0.as_slice() ), &mut output).unwrap();
    dist.write(&output.as_slice()).unwrap();
}

Let's encrypt/decrypt some files!

pub fn encrypt_large_file(
    file_path: &str,
    output_path: &str,
    password: String
) -> Result<(), orion::errors::UnknownCryptoError> {
    let mut source_file = File::open(file_path).expect("Failed to open input file");
    let mut dist = File::create(output_path).expect("Failed to create output file");

    let mut src = Vec::new();
    source_file.read_to_end(&mut src).expect("Failed to read input file");

    let nonce = nonce();

    dist.write(nonce.as_slice()).unwrap();
    let key = create_key(password, nonce.clone());
    let nonce = Nonce::from_slice(nonce.as_slice()).unwrap();

    for (n_chunk, src_chunk) in src.chunks(CHUNK_SIZE).enumerate() {
        encrypt_core(&mut dist, src_chunk.to_vec(), &key, nonce)
    }
    Ok(())
}

pub fn decrypt_large_file(
    file_path: &str, 
    output_path: &str,
    password: String
) -> Result<(), orion::errors::UnknownCryptoError> {
    let mut input_file = File::open(file_path).expect("Failed to open input file");
    let mut output_file = File::create(output_path).expect("Failed to create output file");

    let mut src: Vec<u8> = Vec::new();
    input_file.read_to_end(&mut src).expect("Failed to read input file");

    let nonce = src[..XCHACHA_NONCESIZE].to_vec();

    src = src[XCHACHA_NONCESIZE..].to_vec();

    let key = create_key(password, nonce.clone());
    let nonce = Nonce::from_slice(nonce.as_slice()).unwrap();

    for (n_chunk, src_chunk) in src.chunks(CHUNK_SIZE + CHACHA_KEYSIZE + POLY1305_OUTSIZE).enumerate() {
        decrypt_core(&mut output_file, src_chunk.to_vec(), &key, nonce);
    }

    Ok(())
}

That's it really. Hopefully this is self-explanatory enough but I always welcome comments, questions and improvements (even just telling me I'm wrong but I'd rather know why).

Header image by cottonbro studio: https://www.pexels.com/photo/hand-holding-a-key-with-a-usb-flash-drive-5474298/

Easy Encryption in Typescript 2: Libsodium Boogaloo

Thomas Pegler — Mon, 14 Aug 2023 11:00:00 +0000

Preface: As always, I am not a cryptographer or mathematician. I'm a software engineer who is passionate about encryption and I strive to learn more about it every day but I will make mistakes. If you spot something in here that is incorrect, please let me know so we can help others avoid implementing bad cryptography. Thank you.

In part 1 I discussed the AEAD encryption method, ChaCha20-Poly1305. I also mentioned that, while good, it is not perfect due to the length of the IV (nonce). I also discussed XChaCha20, the improved version and today, I'll show you how you can use that in your Typescript projects using the popular encryption library, libsodium.

TL;DR. Show me the code

npm i libsodium-wrappers
npm i @types/libsodium-wrappers

import _sodium from 'libsodium-wrappers';

await _sodium.ready;
const sodium = _sodium;

const password = process.env.CRYPTO_KEY;


/**
 * Utilises libsodium xChaCha-Poly1305 to encrypt a string.
 * @param {string} plaintext - Plaintext to be encrypted.
 * @returns {string}
 */
export function encrypt( plaintext: string ): string {
  const key = sodium.crypto_kdf_derive_from_key(32, 0, '', Buffer.from( password ) );
  const ad = sodium.randombytes_buf( sodium.crypto_secretstream_xchacha20poly1305_ABYTES );
  const res = sodium.crypto_secretstream_xchacha20poly1305_init_push( key );
  const [ stateOut, header ] = [ res.state, res.header ];
  const c1 = sodium.crypto_secretstream_xchacha20poly1305_push( stateOut,
    sodium.from_string( plaintext ),
    ad,
    sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE );

  const merged = new Uint8Array( header.length + ad.length + c1.length );
  merged.set( header );
  merged.set( ad, header.length );
  merged.set( c1, header.length + ad.length );

  return sodium.to_base64( merged );
}

/**
 * Utilises libsodium xChaCha-Poly1305 to decrypt a string.
 * @param {string} cipherText - Ciphertext to be decrypted.
 * @returns {string}
 */
export function decrypt( cipherText: string ): string {
  const cipher = sodium.from_base64( cipherText );

  const key = sodium.crypto_kdf_derive_from_key(32, 0, '', Buffer.from( password ) );
  const decodedHeader = cipher.slice( 0, sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES );
  const ad = cipher.slice(
    sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES,
    sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES + sodium.crypto_secretstream_xchacha20poly1305_ABYTES,
  );
  const decodedCipherText = cipher.slice( sodium.crypto_secretstream_xchacha20poly1305_ABYTES + sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES );

  const stateIn = sodium.crypto_secretstream_xchacha20poly1305_init_pull( decodedHeader, key );
  const r1 = sodium.crypto_secretstream_xchacha20poly1305_pull( stateIn, decodedCipherText, ad );
  return sodium.to_string( r1.message );
}

With that little TL;DR out of the way, let's actually go through this. First, we need to set up libsodium and ensure it is running.

import _sodium from 'libsodium-wrappers';

await _sodium.ready;
const sodium = _sodium;

Sodium provides a .ready property which is a promise that must resolve before the sodium functions can be used.

export function encrypt( plaintext: string ): string {
  const key = sodium.crypto_kdf_derive_from_key(32, 0, '', Buffer.from( password ) );
  const ad = sodium.randombytes_buf( sodium.crypto_secretstream_xchacha20poly1305_ABYTES );
  const res = sodium.crypto_secretstream_xchacha20poly1305_init_push( key );
  const [ stateOut, header ] = [ res.state, res.header ];
  const c1 = sodium.crypto_secretstream_xchacha20poly1305_push( stateOut,
    sodium.from_string( plaintext ),
    ad,
    sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE );

  const merged = new Uint8Array( header.length + ad.length + c1.length );
  merged.set( header );
  merged.set( ad, header.length );
  merged.set( c1, header.length + ad.length );

  return sodium.to_base64( merged );
}

So we start by using a KDF to generate an encryption key from our password. You can also use libsodium to create a sort of "master key" instead of having a password:

const master = sodium.crypto_secretstream_xchacha20poly1305_keygen();

If you decided to do so, it is important to store these keys securely.

Then, we need an AD, Associated Data (the AD part of AEAD), which we get as random bytes. These should always be random, every time. Do not reuse ADs.

Next, we initialise the State and get the Header (IV/Nonce). With the state initialised and IV returned, we can encrypt with the crypto_secretstream_xchacha20poly1305_push method. After that we simply combine the Header/IV, Associated Data and the encrypted data.

As always, decoding is just the reverse. We derive the key from our "master key". Then split the ciphertext into the Header/IV, AD and the encrypted data. We initialise the state again with the derived key, then we decrypt with the crypto_secretstream_xchacha20poly1305_pull method.

Final thoughts

This process is a little more involved than the previous non-X ChaCha implementation but it not only uses a fantastic, widely supported library in Libsodium, it also ensures an encryption method more secure again nonce-reuse with the larger (192-bit) nonce size.

Header by Brock Wegner on Unsplash

Easy Encryption In Rust

Thomas Pegler — Mon, 07 Aug 2023 11:00:00 +0000

Let's keep this short

I had a whole section planned here for explaining XChaCha and why it's good and what it's good for but, realistically, I don't think many people want to know that and besides, I have another post about why standard ChaCha is good (albeit referencing Typescript) so if you desperately want to know, go read the first article in this series. Or for a better read, I can highly recommend a book called Serious Cryptography by Jean-Philippe Aumasson.

Show me the code!

Here's the overall code for encrypt & decrypt functions

cargo add orion && cargo add rand

This will add the necessary crates to use the functions

// encryption.rs
use std::{error::Error};
use std::fmt::{Debug, Display, Formatter, Result as FmtResult};
use std::fs;
use std::io::{Read, Write};

use orion::hazardous::{
    aead::xchacha20poly1305::{seal, open, Nonce, SecretKey as XSecretKey},
    mac::poly1305::POLY1305_OUTSIZE,
    stream::xchacha20::XCHACHA_NONCESIZE
};
use orion::hazardous::stream::chacha20::CHACHA_KEYSIZE;
use orion::kdf::{derive_key, Password, Salt};
use orion::errors::UnknownCryptoError;
use rand::prelude::*;

#[derive(Debug)]
pub struct CryptoError;

impl Error for CryptoError {}

impl Display for CryptoError {
    fn fmt(&self, f: &mut Formatter) -> FmtResult {
        write!( f, "Crypto failure" )
    }
}

const NONCE_PLUS_AD_SIZE: usize = XCHACHA_NONCESIZE + 32;

/// Split encrypted cipher text into IV, AD and encrypted text
fn split_encrypted( cipher_text: &[u8] ) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    return (
        cipher_text[..XCHACHA_NONCESIZE].to_vec(),
        cipher_text[XCHACHA_NONCESIZE..NONCE_PLUS_AD_SIZE].to_vec(),
        cipher_text[NONCE_PLUS_AD_SIZE..].to_vec(),
    )
}

/// Fill passed array with cryptographically random data from ring crate
fn get_random( dest: &mut [u8]) {
    let mut rng = rand::thread_rng();
    rng.fill( dest );
}

fn nonce() -> Vec<u8> {
    let mut randoms: [u8; 24] = [0; 24];
    get_random( &mut randoms );
    return randoms.to_vec();
}

fn auth_tag() -> Vec<u8> {
    let mut randoms: [u8; 32] = [0; 32];
    get_random( &mut randoms );
    return randoms.to_vec();
}

fn create_key( password: String, nonce: Vec<u8> ) -> XSecretKey {
    let password = Password::from_slice(password.as_bytes()).unwrap();
    let salt = Salt::from_slice(nonce.as_slice()).unwrap();
    let kdf_key = derive_key(&password, &salt, 15, 1024, CHACHA_KEYSIZE as u32).unwrap();
    let key = XSecretKey::from_slice( kdf_key.unprotected_as_bytes() ).unwrap();
    return key;
}

pub fn encrypt( password: String, data: String ) -> Result<Vec<u8>, CryptoError> {
    let nonce = nonce();
    let key = create_key( password, nonce.clone() );
    let nonce = Nonce::from_slice( nonce.as_slice() ).unwrap();
    let ad = auth_tag();

    // Get the output length
    let output_len = match data.len().checked_add( XCHACHA_NONCESIZE + POLY1305_OUTSIZE + ad.len() ) {
        Some( min_output_len ) => min_output_len,
        None => panic!( "Plaintext is too long" ),
    };

    // Allocate a buffer for the output
    let mut output = vec![0u8; output_len];
    output[..XCHACHA_NONCESIZE].copy_from_slice(nonce.as_ref());
    output[XCHACHA_NONCESIZE..NONCE_PLUS_AD_SIZE].copy_from_slice( ad.as_ref() );
    seal(&key, &nonce, data.as_bytes(), Some( ad.clone().as_slice() ), &mut output[NONCE_PLUS_AD_SIZE..]).unwrap();
    let split = split_encrypted( output.as_slice() );
    Ok(output)
}

pub fn decrypt( password: String, cipher_text:String ) -> Result<Vec<u8>, CryptoError> {
    let ciphertext = hex::decode(cipher_text).unwrap();
    let key = create_key(password, ciphertext[..XCHACHA_NONCESIZE].to_vec());
    let split = split_encrypted( ciphertext.as_slice() );
    let nonce = Nonce::from_slice( split.0.as_slice() ).unwrap();
    let mut output = vec![0u8; split.2.len()];

    open(&key, &nonce, split.2.as_slice(), Some( split.1.as_slice() ), &mut output ).unwrap();
    Ok(output.to_vec())
}

And then you can use it a little like this:

// main.rs
mod encryption;

fn encrypt_text(text: String)  -> String {
    let pass = env::var("RUST_PASS").unwrap_or(String::from("Super_Secret_Key_To_Protect_You__"));
    let encrypted = encryption::encrypt(pass, text);

    match encrypted {
        Ok(encrypted) => hex::encode(encrypted),
        Err(e) => {
            info!("{:?}", e);
            String::from("FAILED")
        },
    }
}

fn decrypt_text(text: String)  -> Vec<u8> {
    let pass = env::var( "RUST_PASS" ).unwrap_or(String::from("Super_Secret_Key_To_Protect_You__"));
    let decrypted = encryption::decrypt(pass, text);

    match decrypted {
        Ok(decrypted) => decrypted,
        Err(e) => {
            info!("{:?}", e);
            Vec::new()
        },
    }
}

Is this perfect? Almost certainly not. I'm still learning Rust and trying to find out how best to use encryption crates was a challenge in itself. As always, check with others, learn from others and always try to improve your code whenever you can.

Header by Kaustav Sarkar on Unsplash

Easy Encryption In Typescript

Thomas Pegler — Sun, 06 Aug 2023 09:46:29 +0000

TL;DR: NodeJS Crypto should provide access to ChaCha20-Poly1305 which is a fantastic AEAD Encryption method which should cover the vast majority of use-cases while being fast, modern and strong enough for the foreseeable future.

Cryptography is hard. Good cryptography is even harder. Thankfully, most modern backend services provide many means for making this much easier for modern developers and NodeJS is no different.

When I started diving into NodeJS, trying to find good guides for cryptography in NodeJS was hard. There are a few blogs, some posts but nothing too specific and nothing which provides answers as to why some method is better than others. So I decided to read some books on cryptography and read through some NodeJS documentation.

Basic Encryption With NodeJS

NodeJS provides some useful cryptographic utilities in its crypto module, it allows developers to utilise any algorithms and methods that are available in the locally installed OpenSSL module which, if installed, can be found using the below command on most systems:

openssl list -cipher-algorithms

Which, if openssl is installed, should give you a list that looks like like this:

AES-128-CBC
AES-128-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
AES-128-CFB
AES-128-CFB1
AES-128-CFB8
AES-128-CTR
AES-128-ECB
AES-128-OCB
AES-128-OFB
AES-128-XTS
AES-192-CBC
AES-192-CFB
AES-192-CFB1
AES-192-CFB8
AES-192-CTR
AES-192-ECB
AES-192-OCB
AES-192-OFB
AES-256-CBC
AES-256-CBC-HMAC-SHA1
AES-256-CBC-HMAC-SHA256
. . .

For the majority of people not needing any serious cryptographic security but just looking to secure an application by encrypting some values, aes-256-cbc will be enough, for some semblance of message authentication, using aes-256-cbc-hmac-sha256 will work fine. So let's see what that would look like in Typescript.

AES-256-CBC

import * as crypto from 'crypto';

function splitEncryptedText( encryptedText: string ) {
    return {
        ivString: encryptedText.slice( 0, 32 ),
        encryptedDataString: encryptedText.slice( 32 ),
    }
}

export default class Security {
    encoding: BufferEncoding = 'hex';

    // process.env.CRYPTO_KEY should be a 32 BYTE key
    key: string = process.env.CRYPTO_KEY;

    encrypt( plaintext: string ) {
        try {
            const iv = crypto.randomBytes( 16 );
            const cipher = crypto.createCipheriv( 'aes-256-cbc', this.key, iv );

            const encrypted = Buffer.concat( [
                cipher.update(
                    plaintext, 'utf-8'
                ),
                cipher.final(),
            ] );

            return iv.toString( this.encoding ) + encrypted.toString( this.encoding );

        } catch (e) {
            console.error( e );
        }
    };

    decrypt( cipherText: string ) {
        const {
            encryptedDataString,
            ivString,
        } = splitEncryptedText( cipherText );

        try {
            const iv = Buffer.from( ivString, this.encoding );
            const encryptedText = Buffer.from( encryptedDataString, this.encoding );

            const decipher = crypto.createDecipheriv( 'aes-256-cbc', this.key, iv );

            const decrypted = decipher.update( encryptedText );
            return Buffer.concat( [ decrypted, decipher.final() ] ).toString();
        } catch (e) {
            console.error( e );
        }
    }
}

Let's walk through what's happening here.

First, inside the encrypt method we instantiate an iv, Initialisation Vector, this is used to as the first source for a XOR method in the Chain (CBC stands for Cipher Block Chaining) which encrypts the data. This should always be random, preferably cryptographically secure but doesn't need to be secret.

const iv = crypto.randomBytes( 16 );

Then, we create the encrypt cipher, specifying the algorithm, the key and the IV.

Next, we need to encrypt the text using the cipher.update() method, then calling cipher.final() to close the cipher and ensure no other changes can be made (any further attempts to interact with the cipher result in an error being thrown).

After that, we combine the IV and the encrypted string, converting them both to a specified encoding, I've used hex encoding but that's really not really important, as long as the same encoding is used when decrypting.

Speaking of decrypting, this is just the reverse of encrypting. We split the supplied ciphertext into the encrypted text and the IV, use the IV with a decipher and recover the original text.

As I said, it's remarkably simple and will work for the majority of cases. Now, it should be mentioned that AES-CBC is potentially vulnerable to a Padding Oracle Attack, using the above mentioned aes-256-cbc-hmac-sha256 mitigates this and is most similar to the next method in that is allows for authenticated messages, meaning any attempts to interfere with shouldn't work.

ChaCha20-Poly1305

And now for the main event, a more robust, modern and arguably more secure encryption method. It should be noted that the two methods aren't strictly comparable, plain CBC does not authenticate messages so differs greatly from ChaCha20-Poly1305. That being said, implementing it is very simple and requires only a few line changes from the above example.

import * as crypto from 'crypto';

function splitEncryptedText( encryptedText: string ) {
    return {
        encryptedDataString: encryptedText.slice( 56, -32 ),
        ivString: encryptedText.slice( 0, 24 ),
        assocDataString: encryptedText.slice( 24, 56 ),
        tagString: encryptedText.slice( -32 ),
    }
}

export default class Security {
    encoding: BufferEncoding = 'hex';

    // process.env.CRYPTO_KEY should be a 32 BYTE key
    key: string = process.env.CRYPTO_KEY;

    encrypt( plaintext: string ) {
        try {
            const iv = crypto.randomBytes( 12 );
            const assocData = crypto.randomBytes( 16 );
            const cipher = crypto.createCipheriv( 'chacha20-poly1305', this.key, iv, {
                authTagLength: 16,
            } );

            cipher.setAAD( assocData, { plaintextLength: Buffer.byteLength( plaintext ) } );

            const encrypted = Buffer.concat( [
                cipher.update(
                    plaintext, 'utf-8'
                ),
                cipher.final(),
            ] );
            const tag = cipher.getAuthTag();

            return iv.toString( this.encoding ) + assocData.toString( this.encoding ) + encrypted.toString( this.encoding ) + tag.toString( this.encoding );

        } catch (e) {
            console.error( e );
        }
    };

    decrypt( cipherText: string ) {
        const {
            encryptedDataString,
            ivString,
            assocDataString,
            tagString,
        } = splitEncryptedText( cipherText );

        try {
            const iv = Buffer.from( ivString, this.encoding );
            const encryptedText = Buffer.from( encryptedDataString, this.encoding );
            const tag = Buffer.from( tagString, this.encoding );

            const decipher = crypto.createDecipheriv( 'chacha20-poly1305', this.key, iv, { authTagLength: 16 } );
            decipher.setAAD( Buffer.from( assocDataString, this.encoding ), { plaintextLength: encryptedDataString.length } );
            decipher.setAuthTag( Buffer.from( tag ) );

            const decrypted = decipher.update( encryptedText );
            return Buffer.concat( [ decrypted, decipher.final() ] ).toString();
        } catch (e) {
            console.error( e );
        }
    }
}

Potential issues with ChaCha20-Poly1305

You may be asking, if ChaCha20-Poly1305 is so much better than aes-256-cbc even with hmac-sha256, why even mention them at all? Well, that boils down to something simple. The IV (nonce) size, 96-bits.

While this is generally not a problem, it is smaller than the aes-cbc method which means it is less secure in this aspect. There is a fix for this, XChaCha20-Poly1305 which introduces a 192-bit IV (nonce). Unfortunately, as of yet (30/04/2022), this hasn't made its way into OpenSSL, and thus, not into NodeJS crypto module. So for now, we're stuck with standard ChaCha20-Poly1305 without attempting to implement it ourselves.

Header by rc.xyz NFT gallery on Unsplash