Module fog_crypto::stream

Symmetric-Key encryption.

This submodule provides a StreamKey for symmetric encryption & decryption of any lockbox type. Each StreamKey has a corresponding StreamId for easily identifying the key needed to decrypt a lockbox.

Example

// Make a new temporary key
let mut csprng = rand::rngs::OsRng {};
let key = StreamKey::new_temp(&mut csprng);
let id = key.id().clone();

println!("StreamId(Base58): {}", key.id());

// Encrypt some data with the key, then turn it into a byte vector
let data = b"I am sensitive information, about to be encrypted";
let lockbox = key.encrypt_data(&mut csprng, data.as_ref());
let mut encoded = Vec::new();
encoded.extend_from_slice(lockbox.as_bytes());

// Decrypt that data with the same key
let dec_lockbox = DataLockboxRef::from_bytes(encoded.as_ref())?;
let dec_data = key.decrypt_data(&dec_lockbox)?;

Algorithms

The current (and only) algorithm for symmetric encryption is XChaCha20 with a Poly1305 AEAD construction (XChaCha20Poly1305).

The StreamId is computed by taking the 32-byte secret key and hashing it with BLAKE2b, with the parameters: no key, no salt, and a persona set to “fog-crypto-sid”. 32 bytes of the output hash are used to create the StreamId.

Format

A StreamId is encoded as a version byte followed by the key itself, whose length is dependant on the version. For XChaCha20Poly1305, it is 32 bytes plus the version byte.

A StreamKey is also encoded as a version byte followed by the key itself, whose length is dependant on the version. For XChaCha20Poly1305, it is 32 bytes plus the version byte. This encoding is only ever used for the payload of a StreamLockbox.

See the lockbox module for documentation on the encoding format for encrypted payloads.

Structs

ContainedStreamKey

A self-contained implementor of StreamInterface. It’s expected this will be used unless the symmetric key is being managed by the OS or a hardware module.

StreamId

An identifier for a corresponding StreamKey. It is primarily used to indicate lockboxes are meant for that particular key.

StreamKey

Stream Key that allows encrypting data into a Lockbox and decrypting it later.

Constants

DEFAULT_STREAM_VERSION

Default symmetric-key encryption algorithm version.

MAX_STREAM_VERSION

Maximum accepted symmetric-key encryption algorithm version.

MIN_STREAM_VERSION

Minimum accepted symmetric-key encryption algorithm version.

Traits

StreamInterface

A symmetric encryption/decryption interface, implemented by anything that can hold a symmetric encryption key.

Functions

new_stream_key

Create a new StreamKey to hold a StreamInterface implementation. Can be used by implementors of a vault when making new StreamKey instances.

stream_id_from_key

Compute the corresponding StreamId for a given raw key.

stream_key_encrypt

Encrypt data with a StreamKey, returning a raw byte vector. Implementors of the StreamInterface can use this when building various lockboxes without it showing up in the regular StreamKey interface.