oxicrypto_core/traits/
aead.rs

1use alloc::vec::Vec;
2
3use crate::CryptoError;
4
5/// Authenticated Encryption with Associated Data (AEAD).
6pub trait Aead: Send + Sync {
7    /// Human-readable algorithm identifier (e.g. `"AES-256-GCM"`).
8    #[must_use]
9    fn name(&self) -> &'static str;
10    /// Required key length in bytes.
11    #[must_use]
12    fn key_len(&self) -> usize;
13    /// Required nonce length in bytes.
14    #[must_use]
15    fn nonce_len(&self) -> usize;
16    /// Authentication tag length in bytes appended to ciphertext.
17    #[must_use]
18    fn tag_len(&self) -> usize;
19    /// Encrypt `pt` and write `ciphertext || tag` into `ct_out`.
20    ///
21    /// Returns the number of bytes written (plaintext length + tag length).
22    #[must_use = "result must be checked"]
23    fn seal(
24        &self,
25        key: &[u8],
26        nonce: &[u8],
27        aad: &[u8],
28        pt: &[u8],
29        ct_out: &mut [u8],
30    ) -> Result<usize, CryptoError>;
31    /// Decrypt and authenticate `ct` (ciphertext || tag) into `pt_out`.
32    ///
33    /// Returns the number of bytes written (ciphertext length - tag length).
34    #[must_use = "result must be checked"]
35    fn open(
36        &self,
37        key: &[u8],
38        nonce: &[u8],
39        aad: &[u8],
40        ct: &[u8],
41        pt_out: &mut [u8],
42    ) -> Result<usize, CryptoError>;
43
44    /// Convenience: encrypt and return `ciphertext || tag` as a [`Vec<u8>`].
45    #[must_use = "result must be checked"]
46    fn seal_to_vec(
47        &self,
48        key: &[u8],
49        nonce: &[u8],
50        aad: &[u8],
51        plaintext: &[u8],
52    ) -> Result<Vec<u8>, CryptoError> {
53        let mut out = alloc::vec![0u8; plaintext.len() + self.tag_len()];
54        self.seal(key, nonce, aad, plaintext, &mut out)?;
55        Ok(out)
56    }
57
58    /// Convenience: decrypt and authenticate, returning plaintext as [`Vec<u8>`].
59    ///
60    /// Returns [`CryptoError::BufferTooSmall`] if `ciphertext` is shorter than
61    /// `self.tag_len()`.
62    #[must_use = "result must be checked"]
63    fn open_to_vec(
64        &self,
65        key: &[u8],
66        nonce: &[u8],
67        aad: &[u8],
68        ciphertext: &[u8],
69    ) -> Result<Vec<u8>, CryptoError> {
70        let tag_len = self.tag_len();
71        if ciphertext.len() < tag_len {
72            return Err(CryptoError::BufferTooSmall);
73        }
74        let mut out = alloc::vec![0u8; ciphertext.len() - tag_len];
75        self.open(key, nonce, aad, ciphertext, &mut out)?;
76        Ok(out)
77    }
78}
79
80/// Chunked authenticated encryption with associated data.
81///
82/// Lifecycle: call `init` once, feed chunks with `encrypt_update` /
83/// `decrypt_update`, then call `encrypt_finalize` / `decrypt_finalize`.
84/// Call `reset` to reuse the object.
85pub trait StreamingAead: Sized + Send {
86    /// Initialise the streaming AEAD with key, nonce, and AAD.
87    #[must_use = "result must be checked"]
88    fn init(key: &[u8], nonce: &[u8], aad: &[u8]) -> Result<Self, CryptoError>;
89    /// Feed a plaintext chunk; write ciphertext bytes into `out`.
90    /// Returns the number of bytes written.
91    #[must_use = "result must be checked"]
92    fn encrypt_update(&mut self, chunk: &[u8], out: &mut [u8]) -> Result<usize, CryptoError>;
93    /// Flush remaining ciphertext into `out` and return the 16-byte authentication tag.
94    #[must_use = "result must be checked"]
95    fn encrypt_finalize(self, out: &mut [u8]) -> Result<[u8; 16], CryptoError>;
96    /// Feed a ciphertext chunk; write plaintext bytes into `out`.
97    /// Returns the number of bytes written.
98    #[must_use = "result must be checked"]
99    fn decrypt_update(&mut self, chunk: &[u8], out: &mut [u8]) -> Result<usize, CryptoError>;
100    /// Verify `expected_tag` in constant time and flush remaining plaintext.
101    #[must_use = "result must be checked"]
102    fn decrypt_finalize(self, expected_tag: &[u8]) -> Result<(), CryptoError>;
103    /// Reset to initial (un-initialised) state for reuse.
104    fn reset(&mut self);
105}
oxicrypto_core/traits/aead.rs

oxicrypto_core/traits/
aead.rs
