Struct sio::DecWriter

pub struct DecWriter<A: Algorithm, W: Write> { /* fields omitted */ }

Wraps a writer and decrypts and verifies everything written to it.

DecWriter splits data into fixed-size ciphertext fragments, produced by EncWriter, and decrypts and verifies each fragment separately. It appends any remaining data to its in-memory buffer until it has gathered a complete ciphertext fragment. Therefore, using an std::io::BufWriter in addition usually does not improve the performance of write calls. The only exception may be cases when the buffer size of the BufWriter is significantly larger than the fragment size of the DecWriter.

When the DecWriter is dropped, any buffered content will be decrypted as well as verified and written out. However, any errors that happen in the process of flushing the buffer when the DecWriter is dropped will be ignored. This includes any error indicating that the ciphertext is not authentic! Therefore, code should always call close explicitly to ensure that all ciphertext as been decrypted, verified and written out successfully.

Examples

Let's decrypt a string and store the plaintext in memory:

use std::io::Write;
use sio::{Key, Nonce, Aad, DecWriter, Close};
use sio::ring::AES_256_GCM;

// Load your secret keys from a secure location or derive
// them using a secure (password-based) key-derivation-function, like Argon2id.
// Obviously, don't use this all-zeros key for anything real.
let key: Key<AES_256_GCM> = Key::new([0; Key::<AES_256_GCM>::SIZE]);

// Use the same nonce that was used during encryption.
let nonce = Nonce::new([0; Nonce::<AES_256_GCM>::SIZE]);

// Use the same associated data (AAD) that was used during encryption.
let aad = Aad::from("Some authenticated but not encrypted data".as_bytes());

// The ciphertext as raw byte array.
let ciphertext = [15, 69, 209, 72, 77, 11, 165, 233, 108, 135, 157, 217,
                      175, 75, 229, 217, 210, 88, 148, 173, 187, 7, 208, 154,
                      222, 83, 56, 20, 179, 84, 114, 2, 192, 94, 54, 239, 221, 130];

let mut plaintext: Vec<u8> = Vec::default();  // Store the plaintext in memory.
let mut writer = DecWriter::new(plaintext, &key, nonce, aad);

writer.write_all(&ciphertext).unwrap();
writer.close().unwrap(); // Complete the decryption process explicitly!

Methods

impl<A: Algorithm, W: Write> DecWriter<A, W>

pub fn new(inner: W, key: &Key<A>, nonce: Nonce<A>, aad: Aad) -> Self

Creates a new DecWriter with a default buffer size of 16 KiB.

Anything written to the DecWriter gets decrypted and verified using the provided key and nonce. The aad is only verified and neither decrypted nor written to the inner writer.

Examples

use std::io::Write;
use sio::{Key, Nonce, Aad, DecWriter, Close};
use sio::ring::AES_256_GCM;

// Load your secret keys from a secure location or derive
// them using a secure (password-based) key-derivation-function, like Argon2id.
// Obviously, don't use this all-zeros key for anything real.
let key: Key<AES_256_GCM> = Key::new([0; Key::<AES_256_GCM>::SIZE]);

// Use the same nonce that was used during encryption.
let nonce = Nonce::new([0; Nonce::<AES_256_GCM>::SIZE]);

// Use the same associated data (AAD) that was used during encryption.
let aad = Aad::from("Some authenticated but not encrypted data".as_bytes());

let mut plaintext: Vec<u8> = Vec::default();  // Store the plaintext in memory.
let mut writer = DecWriter::new(plaintext, &key, nonce, aad);

// Perform some write and flush operations
// ...
// For example:
writer.write(&[8, 222, 251, 80, 228, 234, 187, 138, 86, 169, 86, 122, 170, 158, 168, 18]).unwrap();

writer.close().unwrap(); // Complete the decryption process explicitly!

pub fn with_buffer_size(
    inner: W,
    key: &Key<A>,
    nonce: Nonce<A>,
    aad: Aad,
    buf_size: usize
) -> Result<Self, Invalid>

Creates a new DecWriter with the specified buffer size as fragment size. The buf_size must not be 0 nor greater than MAX_BUF_SIZE and must match the buffer size used to encrypt the data.

Anything written to the DecWriter gets decrypted and verified using the provided key and nonce. The aad is only verified and neither decrypted nor written to the inner writer.

It's important to always use the same buffer/fragment size for encrypting and decrypting. Trying to decrypt data that has been encrypted with a different fragment size will fail. Therefore, the buffer size is usually fixed for one (kind of) application.

Examples

Creating an DecWriter with a fragment size of 64 KiB.

use std::io::Write;
use sio::{Key, Nonce, Aad, DecWriter, Close};
use sio::ring::AES_256_GCM;

// Load your secret keys from a secure location or derive
// them using a secure (password-based) key-derivation-function, like Argon2id.
// Obviously, don't use this all-zeros key for anything real.
let key: Key<AES_256_GCM> = Key::new([0; Key::<AES_256_GCM>::SIZE]);

// Use the same nonce that was used for encryption.
let nonce = Nonce::new([0; Nonce::<AES_256_GCM>::SIZE]);

// Use the same associated data (AAD) that was used for encryption.
let aad = Aad::from("Some authenticated but not encrypted data".as_bytes());

let mut plaintext: Vec<u8> = Vec::default();  // Store the plaintext in memory.
let mut writer = DecWriter::with_buffer_size(plaintext, &key, nonce, aad, 64 * 1024).unwrap();

// Perform some write and flush operations
// ...
// For example:
writer.write(&[8, 222, 251, 80, 228, 234, 187, 138, 86, 169, 86, 122, 170, 158, 168, 18]).unwrap();

writer.close().unwrap(); // Complete the encryption process explicitly!

impl<A1: Algorithm, A2: Algorithm, W: Write> DecWriter<A1, EncWriter<A2, W>>

pub fn close(self) -> Result<()>

Complete the decryption by decrypting and verifying the buffered content as last ciphertext fragment and write the plaintext to the inner EncWriter.

If the decryption completes successfully then it also closes the inner EncWriter to complete the inner encryption.

Trait Implementations

impl<A: Algorithm, W: Write> Close for DecWriter<A, W>

fn close(self) -> Result<()>

Tries to close the byte-oriented sinks such that no further operation should succeed. Therefore it consumes the sink.

impl<A: Algorithm, W: Write> Drop for DecWriter<A, W>

fn drop(&mut self)

Executes the destructor for this type.

impl<A: Algorithm, W: Write> Write for DecWriter<A, W>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.