wolf_crypto/aead/chacha20_poly1305/
states.rs

1//! State marker types and traits for the `ChaCha20Poly1305` AEAD.
2//!
3//! This module defines the internal state machine for the `ChaCha20Poly1305` AEAD, using marker
4//! types and traits to enforce correct usage at compile time. It ensures that methods are called in
5//! the correct order and that the AEAD transitions through the appropriate states during encryption
6//! or decryption operations.
7use core::ffi::c_int;
8use wolf_crypto_sys::{CHACHA20_POLY1305_AEAD_DECRYPT, CHACHA20_POLY1305_AEAD_ENCRYPT};
9use crate::sealed::Sealed;
10
11/// Represents the possible states that the [`ChaCha20Poly1305`] AEAD may be in.
12///
13/// [`ChaCha20Poly1305`]: crate::aead::ChaCha20Poly1305
14pub trait State: Sealed {}
15
16define_state! {
17    /// Initial state of the `ChaCha20Poly1305` AEAD.
18    Init,
19
20    /// State where encryption can begin, with optional AAD.
21    ///
22    /// In this state, the cipher is ready to accept optional Additional Authenticated Data (AAD)
23    /// before proceeding to encrypt data.
24    EncryptMaybeAad,
25
26    /// State for updating the AAD during encryption.
27    ///
28    /// In this state, the cipher is in the process of accepting AAD for authentication during
29    /// encryption. Multiple AAD updates can be performed.
30    EncryptAad,
31
32    /// State where encryption of data can occur.
33    ///
34    /// In this state, the cipher can encrypt data and update the authentication tag accordingly.
35    Encrypt,
36
37    /// State where decryption can begin, with optional AAD.
38    ///
39    /// In this state, the cipher is ready to accept optional Additional Authenticated Data (AAD)
40    /// before proceeding to decrypt data.
41    DecryptMaybeAad,
42
43    /// State for updating the AAD during decryption.
44    ///
45    /// In this state, the cipher is in the process of accepting AAD for authentication during
46    /// decryption. Multiple AAD updates can be performed.
47    DecryptAad,
48
49    /// State where decryption of data can occur.
50    ///
51    /// In this state, the cipher can decrypt data and update the authentication tag accordingly.
52    Decrypt,
53}
54
55/// Indicates that the cipher can process data in its current state.
56pub trait CanUpdate: State {
57    /// The mode (encryption or decryption) associated with this state.
58    type Mode: Updating;
59}
60
61/// Defines the behavior for states that can perform the main AEAD operations.
62pub trait Updating: CanUpdate {
63    /// The initial state type when starting the AEAD operation.
64    type InitState: CanSetAad;
65
66    #[doc(hidden)]
67    #[must_use]
68    /// Returns the direction (encrypt or decrypt) for the AEAD operation.
69    fn direction() -> c_int;
70}
71
72/// Indicates that the cipher can update Additional Authenticated Data (AAD) in its current state.
73pub trait CanUpdateAad: State {
74    /// The mode (encryption or decryption) associated with this state.
75    type Updating: UpdatingAad;
76}
77
78/// Indicates that the cipher can either set AAD or proceed to data processing.
79pub trait CanSetAad: CanUpdateAad + CanUpdate {
80    /// The mode (encryption or decryption) associated with this state.
81    type Mode: Updating;
82    /// The associated state for streaming AAD updates.
83    type Updating: UpdatingAad;
84}
85
86/// Defines the behavior for states that are actively updating AAD.
87pub trait UpdatingAad: CanUpdateAad {
88    /// The mode (encryption or decryption) associated with this state. 
89    type Mode: Updating;
90}
91
92// AAD permitted states
93impl CanSetAad for EncryptMaybeAad {
94    type Mode = Encrypt;
95    type Updating = EncryptAad;
96}
97impl CanUpdateAad for EncryptMaybeAad {
98    type Updating = EncryptAad;
99}
100impl CanUpdate for EncryptMaybeAad {
101    type Mode = Encrypt;
102}
103
104impl CanUpdateAad for EncryptAad {
105    type Updating = Self;
106}
107impl UpdatingAad for EncryptAad {
108    type Mode = Encrypt;
109}
110impl<S: UpdatingAad> CanUpdate for S {
111    type Mode = S::Mode;
112}
113
114// ---
115
116impl CanUpdate for Encrypt {
117    type Mode = Self;
118}
119
120impl Updating for Encrypt {
121    type InitState = EncryptMaybeAad;
122
123    #[inline(always)]
124    #[doc(hidden)]
125    fn direction() -> c_int {
126        CHACHA20_POLY1305_AEAD_ENCRYPT as c_int
127    }
128}
129
130// AAD permitted states
131impl CanUpdate for DecryptMaybeAad {
132    type Mode = Decrypt;
133}
134impl CanSetAad for DecryptMaybeAad {
135    type Mode = Decrypt;
136    type Updating = DecryptAad;
137}
138impl CanUpdateAad for DecryptMaybeAad {
139    type Updating = DecryptAad;
140}
141impl CanUpdateAad for DecryptAad {
142    type Updating = Self;
143}
144impl UpdatingAad for DecryptAad {
145    type Mode = Decrypt;
146}
147
148// ---
149
150impl CanUpdate for Decrypt {
151    type Mode = Self;
152}
153impl Updating for Decrypt {
154    type InitState = DecryptMaybeAad;
155
156    #[inline(always)]
157    #[doc(hidden)]
158    fn direction() -> c_int {
159        CHACHA20_POLY1305_AEAD_DECRYPT as c_int
160    }
161}
wolf_crypto/aead/chacha20_poly1305/states.rs

wolf_crypto/aead/chacha20_poly1305/
states.rs
