/rust/registry/src/index.crates.io-6f17d22bba15001f/ring-0.17.14/src/aead.rs

Source (jump to first uncovered line)
// Copyright 2015-2024 Brian Smith.
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

//! Authenticated Encryption with Associated Data (AEAD).
//!
//! See [Authenticated encryption: relations among notions and analysis of the
//! generic composition paradigm][AEAD] for an introduction to the concept of
//! AEADs.
//!
//! [AEAD]: https://eprint.iacr.org/2000/025.pdf
//! [`crypto.cipher.AEAD`]: https://golang.org/pkg/crypto/cipher/#AEAD

use crate::{
    cpu, error,
    polyfill::{u64_from_usize, usize_from_u64_saturated},
};

pub use self::{
    algorithm::{Algorithm, AES_128_GCM, AES_256_GCM, CHACHA20_POLY1305},
    less_safe_key::LessSafeKey,
    nonce::{Nonce, NONCE_LEN},
    opening_key::OpeningKey,
    sealing_key::SealingKey,
    unbound_key::UnboundKey,
};

/// A sequences of unique nonces.
///
/// A given `NonceSequence` must never return the same `Nonce` twice from
/// `advance()`.
///
/// A simple counter is a reasonable (but probably not ideal) `NonceSequence`.
///
/// Intentionally not `Clone` or `Copy` since cloning would allow duplication
/// of the sequence.
pub trait NonceSequence {
    /// Returns the next nonce in the sequence.
    ///
    /// This may fail if "too many" nonces have been requested, where how many
    /// is too many is up to the implementation of `NonceSequence`. An
    /// implementation may that enforce a maximum number of records are
    /// sent/received under a key this way. Once `advance()` fails, it must
    /// fail for all subsequent calls.
    fn advance(&mut self) -> Result<Nonce, error::Unspecified>;
}

/// An AEAD key bound to a nonce sequence.
pub trait BoundKey<N: NonceSequence>: core::fmt::Debug {
    /// Constructs a new key from the given `UnboundKey` and `NonceSequence`.
    fn new(key: UnboundKey, nonce_sequence: N) -> Self;

    /// The key's AEAD algorithm.
    fn algorithm(&self) -> &'static Algorithm;
}

/// The additionally authenticated data (AAD) for an opening or sealing
/// operation. This data is authenticated but is **not** encrypted.
///
/// The type `A` could be a byte slice `&[u8]`, a byte array `[u8; N]`
/// for some constant `N`, `Vec<u8>`, etc.
#[derive(Clone, Copy)]
pub struct Aad<A>(A);

impl<A: AsRef<[u8]>> Aad<A> {
    /// Construct the `Aad` from the given bytes.
    #[inline]
    pub fn from(aad: A) -> Self {
        Self(aad)
    }
}

impl<A> AsRef<[u8]> for Aad<A>
where
    A: AsRef<[u8]>,
{
    fn as_ref(&self) -> &[u8] {
        self.0.as_ref()
    }
}

impl Aad<[u8; 0]> {
    /// Construct an empty `Aad`.
    pub fn empty() -> Self {
        Self::from([])
    }
}

impl<A> core::fmt::Debug for Aad<A>
where
    A: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_tuple("Aad").field(&self.0).finish()
    }
}

impl<A> PartialEq for Aad<A>
where
    A: PartialEq,
{
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.0.eq(&other.0)
    }
}

impl<A> Eq for Aad<A> where A: Eq {}

#[allow(clippy::large_enum_variant, variant_size_differences)]
#[derive(Clone)]
enum KeyInner {
    AesGcm(aes_gcm::Key),
    ChaCha20Poly1305(chacha20_poly1305::Key),
}

const fn max_input_len(block_len: usize, overhead_blocks_per_nonce: usize) -> usize {
    // Each of our AEADs use a 32-bit block counter so the maximum is the
    // largest input that will not overflow the counter.
    usize_from_u64_saturated(
        ((1u64 << 32) - u64_from_usize(overhead_blocks_per_nonce)) * u64_from_usize(block_len),
    )
}

/// A possibly valid authentication tag.
#[must_use]
#[repr(C)]
#[derive(Clone, Copy)]
pub struct Tag([u8; TAG_LEN]);

impl AsRef<[u8]> for Tag {
    fn as_ref(&self) -> &[u8] {
        self.0.as_ref()
    }
}

impl TryFrom<&[u8]> for Tag {
    type Error = error::Unspecified;

    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
        let raw_tag: [u8; TAG_LEN] = value.try_into().map_err(|_| error::Unspecified)?;
        Ok(Self::from(raw_tag))
    }
}

impl From<[u8; TAG_LEN]> for Tag {
    #[inline]
    fn from(value: [u8; TAG_LEN]) -> Self {
        Self(value)
    }
}

const MAX_KEY_LEN: usize = 32;

// All the AEADs we support use 128-bit tags.
const TAG_LEN: usize = 16;

/// The maximum length of a tag for the algorithms in this module.
pub const MAX_TAG_LEN: usize = TAG_LEN;

mod aes;
mod aes_gcm;
mod algorithm;
mod chacha;
mod chacha20_poly1305;
pub mod chacha20_poly1305_openssh;
mod gcm;
mod less_safe_key;
mod nonce;
mod opening_key;
mod overlapping;
mod poly1305;
pub mod quic;
mod sealing_key;
mod shift;
mod unbound_key;

Line	Count	Source (jump to first uncovered line)
1		// Copyright 2015-2024 Brian Smith.
2		//
3		// Permission to use, copy, modify, and/or distribute this software for any
4		// purpose with or without fee is hereby granted, provided that the above
5		// copyright notice and this permission notice appear in all copies.
6		//
7		// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8		// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9		// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
10		// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11		// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
12		// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
13		// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14
15		//! Authenticated Encryption with Associated Data (AEAD).
16		//!
17		//! See [Authenticated encryption: relations among notions and analysis of the
18		//! generic composition paradigm][AEAD] for an introduction to the concept of
19		//! AEADs.
20		//!
21		//! [AEAD]: https://eprint.iacr.org/2000/025.pdf
22		//! [`crypto.cipher.AEAD`]: https://golang.org/pkg/crypto/cipher/#AEAD
23
24		use crate::{
25		cpu, error,
26		polyfill::{u64_from_usize, usize_from_u64_saturated},
27		};
28
29		pub use self::{
30		algorithm::{Algorithm, AES_128_GCM, AES_256_GCM, CHACHA20_POLY1305},
31		less_safe_key::LessSafeKey,
32		nonce::{Nonce, NONCE_LEN},
33		opening_key::OpeningKey,
34		sealing_key::SealingKey,
35		unbound_key::UnboundKey,
36		};
37
38		/// A sequences of unique nonces.
39		///
40		/// A given `NonceSequence` must never return the same `Nonce` twice from
41		/// `advance()`.
42		///
43		/// A simple counter is a reasonable (but probably not ideal) `NonceSequence`.
44		///
45		/// Intentionally not `Clone` or `Copy` since cloning would allow duplication
46		/// of the sequence.
47		pub trait NonceSequence {
48		/// Returns the next nonce in the sequence.
49		///
50		/// This may fail if "too many" nonces have been requested, where how many
51		/// is too many is up to the implementation of `NonceSequence`. An
52		/// implementation may that enforce a maximum number of records are
53		/// sent/received under a key this way. Once `advance()` fails, it must
54		/// fail for all subsequent calls.
55		fn advance(&mut self) -> Result<Nonce, error::Unspecified>;
56		}
57
58		/// An AEAD key bound to a nonce sequence.
59		pub trait BoundKey<N: NonceSequence>: core::fmt::Debug {
60		/// Constructs a new key from the given `UnboundKey` and `NonceSequence`.
61		fn new(key: UnboundKey, nonce_sequence: N) -> Self;
62
63		/// The key's AEAD algorithm.
64		fn algorithm(&self) -> &'static Algorithm;
65		}
66
67		/// The additionally authenticated data (AAD) for an opening or sealing
68		/// operation. This data is authenticated but is not encrypted.
69		///
70		/// The type `A` could be a byte slice `&[u8]`, a byte array `[u8; N]`
71		/// for some constant `N`, `Vec<u8>`, etc.
72		#[derive(Clone, Copy)]
73		pub struct Aad<A>(A);
74
75		impl<A: AsRef<[u8]>> Aad<A> {
76		/// Construct the `Aad` from the given bytes.
77		#[inline]
78	0	pub fn from(aad: A) -> Self {
79	0	Self(aad)
80	0	} Unexecuted instantiation: <ring::aead::Aad<[u8; 0]>>::from Unexecuted instantiation: <ring::aead::Aad<&[u8]>>::from
81		}
82
83		impl<A> AsRef<[u8]> for Aad<A>
84		where
85		A: AsRef<[u8]>,
86		{
87	0	fn as_ref(&self) -> &[u8] {
88	0	self.0.as_ref()
89	0	}
90		}
91
92		impl Aad<[u8; 0]> {
93		/// Construct an empty `Aad`.
94	0	pub fn empty() -> Self {
95	0	Self::from([])
96	0	}
97		}
98
99		impl<A> core::fmt::Debug for Aad<A>
100		where
101		A: core::fmt::Debug,
102		{
103	0	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
104	0	f.debug_tuple("Aad").field(&self.0).finish()
105	0	}
106		}
107
108		impl<A> PartialEq for Aad<A>
109		where
110		A: PartialEq,
111		{
112		#[inline]
113	0	fn eq(&self, other: &Self) -> bool {
114	0	self.0.eq(&other.0)
115	0	}
116		}
117
118		impl<A> Eq for Aad<A> where A: Eq {}
119
120		#[allow(clippy::large_enum_variant, variant_size_differences)]
121		#[derive(Clone)]
122		enum KeyInner {
123		AesGcm(aes_gcm::Key),
124		ChaCha20Poly1305(chacha20_poly1305::Key),
125		}
126
127	0	const fn max_input_len(block_len: usize, overhead_blocks_per_nonce: usize) -> usize {
128	0	// Each of our AEADs use a 32-bit block counter so the maximum is the
129	0	// largest input that will not overflow the counter.
130	0	usize_from_u64_saturated(
131	0	((1u64 << 32) - u64_from_usize(overhead_blocks_per_nonce)) * u64_from_usize(block_len),
132	0	)
133	0	}
134
135		/// A possibly valid authentication tag.
136		#[must_use]
137		#[repr(C)]
138		#[derive(Clone, Copy)]
139		pub struct Tag([u8; TAG_LEN]);
140
141		impl AsRef<[u8]> for Tag {
142	0	fn as_ref(&self) -> &[u8] {
143	0	self.0.as_ref()
144	0	}
145		}
146
147		impl TryFrom<&[u8]> for Tag {
148		type Error = error::Unspecified;
149
150	0	fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
151	0	let raw_tag: [u8; TAG_LEN] = value.try_into().map_err(\|_\| error::Unspecified)?;
152	0	Ok(Self::from(raw_tag))
153	0	}
154		}
155
156		impl From<[u8; TAG_LEN]> for Tag {
157		#[inline]
158	0	fn from(value: [u8; TAG_LEN]) -> Self {
159	0	Self(value)
160	0	}
161		}
162
163		const MAX_KEY_LEN: usize = 32;
164
165		// All the AEADs we support use 128-bit tags.
166		const TAG_LEN: usize = 16;
167
168		/// The maximum length of a tag for the algorithms in this module.
169		pub const MAX_TAG_LEN: usize = TAG_LEN;
170
171		mod aes;
172		mod aes_gcm;
173		mod algorithm;
174		mod chacha;
175		mod chacha20_poly1305;
176		pub mod chacha20_poly1305_openssh;
177		mod gcm;
178		mod less_safe_key;
179		mod nonce;
180		mod opening_key;
181		mod overlapping;
182		mod poly1305;
183		pub mod quic;
184		mod sealing_key;
185		mod shift;
186		mod unbound_key;

Coverage Report

Created: 2025-07-01 06:46