Struct RootKey 

pub struct RootKey { /* private fields */ }

Originating Key

This key consists of an independently, randomly generated encryption key, HMAC key, and an entropy pool for generating derived keys.

While the components are generated independently from any user provided input, at rest encryption of this key material is achieved by encrypting the RootKey using an argon2 derivation of a user supplied password. This decoupling of key generation from user input allows several useful things, such as allowing the password for a store to be changed without having to reencrypt all the data, as well as making entire categories of attacks effectively impossible.

The included encryption and HMAC keys should only be used for encrypting top-level metadata, to limit the amount of data encrypted with this key. Derived keys can be produced with a namespace string via the derive method.

Implementations

impl RootKey

pub fn random() -> Self

Generates a new RootKey

This method uses a cryptograpically secure random number generator to fill the encryption key, HMAC key, and entropy pools with random data.

RootKeys should always be randomly generated, and there is intentionally no API for recreating a specific RootKey

pub fn null() -> Self

Creates an all zero RootKey, also known as ‘The null key’

DANGER

This method exists because this library does not support operating on plaintext at rest data, so the all-zero key is used as a known-ahead-of-time key for passwordless use.

This is, hopefully obviously, incredibly insecure, and should only ever be called when storing data in plaintext would be appropriate.

pub fn encrypt(&self, password: &[u8]) -> Result<EncryptedRootKey, BackendError>

Encrypts this key, producing a EncryptedRootKey, with the provided password.

This uses a byte slice rather than a string to provide more flexibility.

Argon2 and a random salt are used to generate 64 bytes of key material from the user supplied password, the first 32 bytes of which are used as the encryption key, and the last 32 bytes are used as an HMAC key. This allows us to use the password to provide both encryption and authentication.

Errors

Will return:

• Error::Argon2Failure if the argon2 key derivation fails

pub fn derive(&self, namespace: &str) -> DerivedKey

Creates a DerivedKey from this RootKey using the provided namespace as part of the context string

This method will generate, using a CSPRNG a random, 32 character, hexadecimal nonce (~128 bits of entropy) to include in the context string, which will then be combined with the provided namespace and fed into Blake3’s key derivation mode. Blake3 is used to derive 64 bytes of key material, the first 32 bytes of which are used as an encryption key, and the last 32 bytes of which are used as an HMAC key.

While DerivedKey can be used quite safely for a large number of encryptions, it is wise to limit the usage of an individual DerivedKey as much as possible, to limit the fallout of any accidental/unintentional nonce reuses.

pub fn derive_with_context(&self, context_string: String) -> DerivedKey

Creates a DerivedKey from this RootKey with a specified context string

DANGER

The derive method intentionally includes a random component to facilitate key rotation. Using this method for any other purpose then to rederive a lost key is dangerous, as it can lead to unintended key reuse.

Trait Implementations

impl Clone for RootKey

fn clone(&self) -> RootKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'de> Deserialize<'de> for RootKey

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Drop for RootKey

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for RootKey

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Key for RootKey

fn encryption_key(&self) -> &Key

Provides the encryption key as a chacha Key

fn hmac_key(&self) -> &[u8; 32]

Provides the hmac key as a reference to the underlying array

impl Serialize for RootKey

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Zeroize for RootKey

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.