Struct RotatingStrongBox 

pub struct RotatingStrongBox { /* private fields */ }

A StrongBox variant that uses a different set of keys for each period of time.

This box is primarily useful when you’re encrypting data that only has to be valid for a relatively short period of time (such as browser cookies and other shortish-lived tokens). It is particularly beneficial if you could potentially do a lot (ie “many billions”) of encryptions over the lifetime of the root keys (because, for various tedious reasons, the risk of a cryptographic break increases based on the number of different encryptions done by one key).

To use it, you need to specify the “root” encryption and decryption keys, as with any other strong box, but also the Duration for which key is valid, and also the number of previous time periods which you want to still be able to decrypt.

The way it works is that time is divided up into periods, each of which has a Duration of lifespan, specified when the RotatingStrongBox is created. When an encryption operation is performed, the current period is determined (by looking at the clock and divided by lifespan), the encryption key for the current period is derived from the “root” encryption key, and the data is encrypted as normal with that “current encryption key”. So far, so good.

When a ciphertext is presented for decryption, things get a bit more involved. The RotatingStrongBox needs to figure out which key to use for decryption, by deriving the decryption keys from the “root” decryption keys specified when the RotatingStrongBox was created, both for the time period at the time the decryption happens, as well as the previous time periods, up to the limit specified by backtrack. If the decryption key for the ciphertext is one of those keys, then decryption happens as normal. Otherwise, you’re out of luck, and the decryption fails.

Since deriving lots of keys can start to take a little bit of time, the set of decryption keys is cached, and also shared amongst all the clones of a given RotatingStrongBox. The maximum amount of memory that will be used by the cache (and the amount of time needed to derive all the keys) is determined by the number of separate decryption keys, multiplied by the number of backtrack periods allowed. Each key is relatively small, so don’t worry too much, but also don’t go “oh, I’ll make my key lifespan 30 seconds and cache keys for 10 years” without being ready for a certain amount of bloat.

Trait Implementations

impl Clone for RotatingStrongBox

fn clone(&self) -> RotatingStrongBox

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RotatingStrongBox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl StrongBox for RotatingStrongBox

fn encrypt( &self, plaintext: impl AsRef<[u8]>, ctx: impl AsRef<[u8]> + Debug, ) -> Result<Vec<u8>, Error>

Encrypt secret data using the StrongBox’s encryption key, within the StrongBox’s specified context.

fn decrypt( &self, ciphertext: impl AsRef<[u8]>, ctx: impl AsRef<[u8]> + Debug, ) -> Result<Vec<u8>, Error>

Decrypt a ciphertext, using any valid key for the StrongBox, and validate that the ciphertext was encrypted with the specified context.

impl UnwindSafe for RotatingStrongBox