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 AUTHORS DISCLAIM ALL WARRANTIES
8// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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
24use crate::{
25 cpu, error,
26 polyfill::{u64_from_usize, usize_from_u64_saturated},
27};
28
29pub 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.
47pub 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.
59pub 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)]
73pub struct Aad<A>(A);
74
75impl<A: AsRef<[u8]>> Aad<A> {
76 /// Construct the `Aad` from the given bytes.
77 #[inline]
78 pub fn from(aad: A) -> Self {
79 Self(aad)
80 }
81}
82
83impl<A> AsRef<[u8]> for Aad<A>
84where
85 A: AsRef<[u8]>,
86{
87 fn as_ref(&self) -> &[u8] {
88 self.0.as_ref()
89 }
90}
91
92impl Aad<[u8; 0]> {
93 /// Construct an empty `Aad`.
94 pub fn empty() -> Self {
95 Self::from([])
96 }
97}
98
99impl<A> core::fmt::Debug for Aad<A>
100where
101 A: core::fmt::Debug,
102{
103 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
104 f.debug_tuple(name:"Aad").field(&self.0).finish()
105 }
106}
107
108impl<A> PartialEq for Aad<A>
109where
110 A: PartialEq,
111{
112 #[inline]
113 fn eq(&self, other: &Self) -> bool {
114 self.0.eq(&other.0)
115 }
116}
117
118impl<A> Eq for Aad<A> where A: Eq {}
119
120#[allow(clippy::large_enum_variant, variant_size_differences)]
121#[derive(Clone)]
122enum KeyInner {
123 AesGcm(aes_gcm::Key),
124 ChaCha20Poly1305(chacha20_poly1305::Key),
125}
126
127const fn max_input_len(block_len: usize, overhead_blocks_per_nonce: usize) -> usize {
128 // Each of our AEADs use a 32-bit block counter so the maximum is the
129 // largest input that will not overflow the counter.
130 usize_from_u64_saturated(
131 ((1u64 << 32) - u64_from_usize(overhead_blocks_per_nonce)) * u64_from_usize(block_len),
132 )
133}
134
135/// A possibly valid authentication tag.
136#[must_use]
137#[repr(C)]
138#[derive(Clone, Copy)]
139pub struct Tag([u8; TAG_LEN]);
140
141impl AsRef<[u8]> for Tag {
142 fn as_ref(&self) -> &[u8] {
143 self.0.as_ref()
144 }
145}
146
147impl TryFrom<&[u8]> for Tag {
148 type Error = error::Unspecified;
149
150 fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
151 let raw_tag: [u8; TAG_LEN] = value.try_into().map_err(|_| error::Unspecified)?;
152 Ok(Self::from(raw_tag))
153 }
154}
155
156impl From<[u8; TAG_LEN]> for Tag {
157 #[inline]
158 fn from(value: [u8; TAG_LEN]) -> Self {
159 Self(value)
160 }
161}
162
163const MAX_KEY_LEN: usize = 32;
164
165// All the AEADs we support use 128-bit tags.
166const TAG_LEN: usize = 16;
167
168/// The maximum length of a tag for the algorithms in this module.
169pub const MAX_TAG_LEN: usize = TAG_LEN;
170
171mod aes;
172mod aes_gcm;
173mod algorithm;
174mod chacha;
175mod chacha20_poly1305;
176pub mod chacha20_poly1305_openssh;
177mod gcm;
178mod less_safe_key;
179mod nonce;
180mod opening_key;
181mod overlapping;
182mod poly1305;
183pub mod quic;
184mod sealing_key;
185mod shift;
186mod unbound_key;
187