vitaminc-aead 0.3.0

Authenticated Encryption with Associated Data (AEAD) primitives. Part of the Vitamin-C cryptographic suite.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

//! The decrypt-side counterpart to the [`encrypt`](crate::encrypt) module.
//!
//! [`Decrypt`] is to [`Decipher`](crate::Decipher) what
//! [`Encrypt`](crate::Encrypt) is to [`Cipher`](crate::Cipher): the trait a
//! plaintext type implements to describe how it decodes itself, kept separate
//! from the traits a cipher backend implements to drive that decoding.

pub mod impls;

use crate::{Aad, Decipher, IntoAad};
use vitaminc_protected::{Controlled, Protected};
use zeroize::Zeroize;

/// The counterpart to `Encrypt` — a type that knows how to decrypt itself using a `Decipher`.
/// Analogous to serde's `Deserialize`.
pub trait Decrypt<'c>: Sized + Send {
    /// Decrypt `Self` from the given decipher with no associated data.
    ///
    /// Convenience wrapper around [`decrypt_with_aad`](Decrypt::decrypt_with_aad), mirroring
    /// [`Encrypt::encrypt`](crate::Encrypt::encrypt).
    fn decrypt<D: Decipher<'c>>(decipher: D) -> D::Ok<Self> {
        Self::decrypt_with_aad(decipher, Aad::empty())
    }

    /// Decrypt `Self` from the given decipher, authenticating against `aad`.
    ///
    /// This is the method implementations provide; it mirrors
    /// [`Encrypt::encrypt_with_aad`](crate::Encrypt::encrypt_with_aad). The `aad` must match
    /// the associated data bound at encrypt time or decryption fails.
    fn decrypt_with_aad<'a, D, A>(decipher: D, aad: A) -> D::Ok<Self>
    where
        D: Decipher<'c>,
        A: IntoAad<'a>;

    /// Decrypt straight into a `Protected<Self>`.
    ///
    /// The counterpart to [`Encrypt::encrypt_protected`](crate::Encrypt::encrypt_protected),
    /// and the seam the blanket `impl Decrypt for Protected<T>` goes through.
    /// The default decrypts a bare `Self` and wraps it, which is right for
    /// composite types. Byte leaves override it to keep the
    /// `Protected<Vec<u8>>` the decipher already hands to
    /// [`DecipherVisitor::visit_bytes_vec`](crate::DecipherVisitor::visit_bytes_vec)
    /// wrapped the whole way out, rather than unwrapping it only to wrap it again.
    fn decrypt_protected<'a, D, A>(decipher: D, aad: A) -> D::Ok<Protected<Self>>
    where
        Self: Zeroize + 'c,
        D: Decipher<'c>,
        A: IntoAad<'a>,
    {
        D::map_ok(
            Self::decrypt_with_aad(decipher, aad),
            Protected::init_from_inner,
        )
    }
}