Skip to main content

bitwarden_crypto/safe/
helpers.rs

1use std::fmt::DebugStruct;
2
3use ciborium::Value;
4
5use crate::cose::{
6    ContentNamespace, SAFE_CONTENT_NAMESPACE, SAFE_OBJECT_NAMESPACE, SafeObjectNamespace,
7    extract_integer, symmetric::CoseContentEncryptionAlgorithm,
8};
9
10#[derive(Debug)]
11pub(super) enum ExtractionError {
12    MissingNamespace,
13    InvalidNamespace,
14}
15
16pub(super) fn extract_safe_object_namespace(
17    header: &coset::Header,
18) -> Result<SafeObjectNamespace, ExtractionError> {
19    match extract_integer(header, SAFE_OBJECT_NAMESPACE, "safe object namespace") {
20        Ok(value) => value
21            .try_into()
22            .map_err(|_| ExtractionError::InvalidNamespace),
23        Err(_) => Err(ExtractionError::MissingNamespace),
24    }
25}
26
27pub(super) fn extract_safe_content_namespace<T: ContentNamespace>(
28    header: &coset::Header,
29) -> Result<T, ExtractionError> {
30    match extract_integer(header, SAFE_CONTENT_NAMESPACE, "safe content namespace") {
31        Ok(value) => value
32            .try_into()
33            .map_err(|_| ExtractionError::InvalidNamespace),
34        Err(_) => Err(ExtractionError::MissingNamespace),
35    }
36}
37
38pub(super) fn debug_fmt<C: ContentNamespace>(
39    debug_struct: &mut DebugStruct,
40    header: &coset::Header,
41) {
42    if let Ok(object_namespace) = extract_safe_object_namespace(header) {
43        debug_struct.field("object_namespace", &object_namespace);
44    }
45    if let Ok(content_namespace) = extract_safe_content_namespace::<C>(header) {
46        debug_struct.field("content_namespace", &content_namespace);
47    }
48    if let Some(algorithm) = header.alg.as_ref()
49        && let Ok(content_encryption_algorithm) =
50            CoseContentEncryptionAlgorithm::try_from(algorithm)
51    {
52        let label = match content_encryption_algorithm {
53            CoseContentEncryptionAlgorithm::Aes256Gcm => "AES-256-GCM",
54            CoseContentEncryptionAlgorithm::XAes256Gcm => "XAES-256-GCM",
55            CoseContentEncryptionAlgorithm::XChaCha20Poly1305 => "XChaCha20-Poly1305",
56            CoseContentEncryptionAlgorithm::Aes256CbcHmacSha256Aead => {
57                "AES-256-CBC-HMAC-SHA256-AEAD"
58            }
59        };
60        debug_struct.field("content_encryption_algorithm", &label);
61    }
62}
63
64pub(super) fn set_header_value(header: &mut coset::Header, label: i64, value: Value) {
65    if let Some((_, existing_value)) =
66        header
67            .rest
68            .iter_mut()
69            .find(|(existing_label, _)| matches!(existing_label, coset::Label::Int(existing) if *existing == label))
70    {
71        *existing_value = value;
72    } else {
73        header.rest.push((coset::Label::Int(label), value));
74    }
75}
76
77pub(super) fn set_safe_namespaces<T: ContentNamespace>(
78    header: &mut coset::Header,
79    object_namespace: SafeObjectNamespace,
80    content_namespace: T,
81) {
82    set_header_value(
83        header,
84        SAFE_OBJECT_NAMESPACE,
85        Value::from(i128::from(object_namespace)),
86    );
87    set_header_value(
88        header,
89        SAFE_CONTENT_NAMESPACE,
90        Value::from(content_namespace.into()),
91    );
92}
93
94/// Validates the provided header contains the expected object and content namespace.
95/// For backward compatibility, missing values are OK, but incorrect values are not.
96/// The validation happens individually for both namespace layers, and either one
97/// missing with the other being present is OK.
98pub(super) fn validate_safe_namespaces<T: ContentNamespace>(
99    header: &coset::Header,
100    expected_object_namespace: SafeObjectNamespace,
101    expected_content_namespace: T,
102) -> Result<(), ExtractionError> {
103    match extract_safe_object_namespace(header) {
104        Ok(ns) if ns == expected_object_namespace => (),
105        // If the namespace is present but doesn't match, return an error immediately.
106        Ok(_) => return Err(ExtractionError::InvalidNamespace),
107        // If the namespace is missing, do not validate for backward compatibility
108        Err(ExtractionError::MissingNamespace) => (),
109        // If the namespace is present but invalid (e.g., not an integer or out of range), return an
110        // error.
111        Err(ExtractionError::InvalidNamespace) => return Err(ExtractionError::InvalidNamespace),
112    }
113
114    match extract_safe_content_namespace::<T>(header) {
115        Ok(ns) if ns == expected_content_namespace => Ok(()),
116        // If the namespace is present but doesn't match, return an error immediately.
117        Ok(_) => Err(ExtractionError::InvalidNamespace),
118        // If the namespace is missing, do not validate for backward compatibility
119        Err(ExtractionError::MissingNamespace) => Ok(()),
120        // If the namespace is present but invalid (e.g., not an integer or out of range), return an
121        // error.
122        Err(ExtractionError::InvalidNamespace) => Err(ExtractionError::InvalidNamespace),
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use ciborium::Value;
129
130    use super::*;
131    use crate::{cose::SAFE_OBJECT_NAMESPACE, safe::DataEnvelopeNamespace};
132
133    fn count_label(header: &coset::Header, label: i64) -> usize {
134        header
135            .rest
136            .iter()
137            .filter(
138                |(existing_label, _)| {
139                    matches!(existing_label, coset::Label::Int(existing) if *existing == label)
140                },
141            )
142            .count()
143    }
144
145    fn extract_safe_namespaces<T: ContentNamespace>(
146        header: &coset::Header,
147    ) -> Result<(SafeObjectNamespace, T), ExtractionError> {
148        let object_namespace = extract_safe_object_namespace(header)?;
149        let content_namespace = extract_safe_content_namespace(header)?;
150
151        Ok((object_namespace, content_namespace))
152    }
153
154    #[test]
155    fn set_safe_namespaces_sets_both_namespace_labels() {
156        let mut header = coset::HeaderBuilder::new().build();
157
158        set_safe_namespaces(
159            &mut header,
160            SafeObjectNamespace::DataEnvelope,
161            DataEnvelopeNamespace::ExampleNamespace,
162        );
163
164        let extracted = extract_safe_namespaces::<DataEnvelopeNamespace>(&header);
165        assert!(matches!(
166            extracted,
167            Ok((
168                SafeObjectNamespace::DataEnvelope,
169                DataEnvelopeNamespace::ExampleNamespace
170            ))
171        ));
172    }
173
174    #[test]
175    fn set_safe_namespaces_overwrites_existing_namespace_values() {
176        let mut header = coset::HeaderBuilder::new()
177            .value(SAFE_OBJECT_NAMESPACE, Value::from(999_i64))
178            .value(SAFE_CONTENT_NAMESPACE, Value::from(999_i64))
179            .build();
180
181        set_safe_namespaces(
182            &mut header,
183            SafeObjectNamespace::DataEnvelope,
184            DataEnvelopeNamespace::ExampleNamespace,
185        );
186
187        assert_eq!(count_label(&header, SAFE_OBJECT_NAMESPACE), 1);
188        assert_eq!(count_label(&header, SAFE_CONTENT_NAMESPACE), 1);
189        assert!(matches!(
190            extract_safe_namespaces::<DataEnvelopeNamespace>(&header),
191            Ok((
192                SafeObjectNamespace::DataEnvelope,
193                DataEnvelopeNamespace::ExampleNamespace
194            ))
195        ));
196    }
197
198    #[test]
199    fn extract_safe_namespaces_fails_when_namespace_missing() {
200        let header = coset::HeaderBuilder::new().build();
201
202        assert!(matches!(
203            extract_safe_namespaces::<DataEnvelopeNamespace>(&header),
204            Err(ExtractionError::MissingNamespace)
205        ));
206    }
207
208    #[test]
209    fn extract_safe_namespaces_fails_when_namespace_invalid() {
210        let header = coset::HeaderBuilder::new()
211            .value(
212                SAFE_OBJECT_NAMESPACE,
213                Value::from(SafeObjectNamespace::DataEnvelope as i64),
214            )
215            .value(SAFE_CONTENT_NAMESPACE, Value::from(999_i64))
216            .build();
217
218        assert!(matches!(
219            extract_safe_namespaces::<DataEnvelopeNamespace>(&header),
220            Err(ExtractionError::InvalidNamespace)
221        ));
222    }
223
224    #[test]
225    fn validate_safe_namespaces_allows_missing_labels_for_backwards_compat() {
226        let header = coset::HeaderBuilder::new().build();
227
228        let result = validate_safe_namespaces(
229            &header,
230            SafeObjectNamespace::DataEnvelope,
231            DataEnvelopeNamespace::ExampleNamespace,
232        );
233        assert!(result.is_ok());
234    }
235
236    #[test]
237    fn validate_safe_namespaces_rejects_namespace_mismatch() {
238        let mut header = coset::HeaderBuilder::new().build();
239        set_safe_namespaces(
240            &mut header,
241            SafeObjectNamespace::DataEnvelope,
242            DataEnvelopeNamespace::ExampleNamespace,
243        );
244
245        let result = validate_safe_namespaces(
246            &header,
247            SafeObjectNamespace::DataEnvelope,
248            DataEnvelopeNamespace::ExampleNamespace2,
249        );
250        assert!(matches!(result, Err(ExtractionError::InvalidNamespace)));
251    }
252}