xmpp_parsers/
hashes.rs

1// Copyright (c) 2017 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7use alloc::borrow::Cow;
8use core::{
9    num::ParseIntError,
10    ops::{Deref, DerefMut},
11    str::FromStr,
12};
13
14use xso::{error::Error, text::Base64, AsXml, AsXmlText, FromXml, FromXmlText};
15
16use base64::{engine::general_purpose::STANDARD as Base64Engine, Engine};
17use minidom::IntoAttributeValue;
18
19use crate::ns;
20
21/// List of the algorithms we support, or Unknown.
22#[allow(non_camel_case_types)]
23#[derive(Debug, Clone, PartialEq, Eq, Hash)]
24pub enum Algo {
25    /// The Secure Hash Algorithm 1, with known vulnerabilities, do not use it.
26    ///
27    /// See <https://www.rfc-editor.org/rfc/rfc3174>
28    Sha_1,
29
30    /// The Secure Hash Algorithm 2, in its 256-bit version.
31    ///
32    /// See <https://www.rfc-editor.org/rfc/rfc6234>
33    Sha_256,
34
35    /// The Secure Hash Algorithm 2, in its 512-bit version.
36    ///
37    /// See <https://www.rfc-editor.org/rfc/rfc6234>
38    Sha_512,
39
40    /// The Secure Hash Algorithm 3, based on Keccak, in its 256-bit version.
41    ///
42    /// See <https://keccak.team/files/Keccak-submission-3.pdf>
43    Sha3_256,
44
45    /// The Secure Hash Algorithm 3, based on Keccak, in its 512-bit version.
46    ///
47    /// See <https://keccak.team/files/Keccak-submission-3.pdf>
48    Sha3_512,
49
50    /// The BLAKE2 hash algorithm, for a 256-bit output.
51    ///
52    /// See <https://www.rfc-editor.org/rfc/rfc7693>
53    Blake2b_256,
54
55    /// The BLAKE2 hash algorithm, for a 512-bit output.
56    ///
57    /// See <https://www.rfc-editor.org/rfc/rfc7693>
58    Blake2b_512,
59
60    /// An unknown hash not in this list, you can probably reject it.
61    Unknown(String),
62}
63
64impl FromStr for Algo {
65    type Err = Error;
66
67    fn from_str(s: &str) -> Result<Algo, Error> {
68        Ok(match s {
69            "" => return Err(Error::Other("'algo' argument can’t be empty.")),
70
71            "sha-1" => Algo::Sha_1,
72            "sha-256" => Algo::Sha_256,
73            "sha-512" => Algo::Sha_512,
74            "sha3-256" => Algo::Sha3_256,
75            "sha3-512" => Algo::Sha3_512,
76            "blake2b-256" => Algo::Blake2b_256,
77            "blake2b-512" => Algo::Blake2b_512,
78            value => Algo::Unknown(value.to_owned()),
79        })
80    }
81}
82
83impl From<Algo> for String {
84    fn from(algo: Algo) -> String {
85        String::from(match algo {
86            Algo::Sha_1 => "sha-1",
87            Algo::Sha_256 => "sha-256",
88            Algo::Sha_512 => "sha-512",
89            Algo::Sha3_256 => "sha3-256",
90            Algo::Sha3_512 => "sha3-512",
91            Algo::Blake2b_256 => "blake2b-256",
92            Algo::Blake2b_512 => "blake2b-512",
93            Algo::Unknown(text) => return text,
94        })
95    }
96}
97
98impl FromXmlText for Algo {
99    fn from_xml_text(value: String) -> Result<Self, Error> {
100        value.parse().map_err(Error::text_parse_error)
101    }
102}
103
104impl AsXmlText for Algo {
105    fn as_xml_text(&self) -> Result<Cow<'_, str>, Error> {
106        Ok(Cow::Borrowed(match self {
107            Algo::Sha_1 => "sha-1",
108            Algo::Sha_256 => "sha-256",
109            Algo::Sha_512 => "sha-512",
110            Algo::Sha3_256 => "sha3-256",
111            Algo::Sha3_512 => "sha3-512",
112            Algo::Blake2b_256 => "blake2b-256",
113            Algo::Blake2b_512 => "blake2b-512",
114            Algo::Unknown(text) => text.as_str(),
115        }))
116    }
117}
118
119impl IntoAttributeValue for Algo {
120    fn into_attribute_value(self) -> Option<String> {
121        Some(String::from(self))
122    }
123}
124
125/// This element represents a hash of some data, defined by the hash
126/// algorithm used and the computed value.
127#[derive(FromXml, AsXml, PartialEq, Debug, Clone)]
128#[xml(namespace = ns::HASHES, name = "hash")]
129pub struct Hash {
130    /// The algorithm used to create this hash.
131    #[xml(attribute)]
132    pub algo: Algo,
133
134    /// The hash value, as a vector of bytes.
135    #[xml(text = Base64)]
136    pub hash: Vec<u8>,
137}
138
139impl Hash {
140    /// Creates a [struct@Hash] element with the given algo and data.
141    pub fn new(algo: Algo, hash: Vec<u8>) -> Hash {
142        Hash { algo, hash }
143    }
144
145    /// Like [new](#method.new) but takes base64-encoded data before decoding
146    /// it.
147    pub fn from_base64(algo: Algo, hash: &str) -> Result<Hash, Error> {
148        Ok(Hash::new(
149            algo,
150            Base64Engine.decode(hash).map_err(Error::text_parse_error)?,
151        ))
152    }
153
154    /// Like [new](#method.new) but takes hex-encoded data before decoding it.
155    pub fn from_hex(algo: Algo, hex: &str) -> Result<Hash, ParseIntError> {
156        let mut bytes = vec![];
157        for i in 0..hex.len() / 2 {
158            let byte = u8::from_str_radix(&hex[2 * i..2 * i + 2], 16)?;
159            bytes.push(byte);
160        }
161        Ok(Hash::new(algo, bytes))
162    }
163
164    /// Like [new](#method.new) but takes hex-encoded data before decoding it.
165    pub fn from_colon_separated_hex(algo: Algo, hex: &str) -> Result<Hash, ParseIntError> {
166        let mut bytes = vec![];
167        for i in 0..(1 + hex.len()) / 3 {
168            let byte = u8::from_str_radix(&hex[3 * i..3 * i + 2], 16)?;
169            if 3 * i + 2 < hex.len() {
170                assert_eq!(&hex[3 * i + 2..3 * i + 3], ":");
171            }
172            bytes.push(byte);
173        }
174        Ok(Hash::new(algo, bytes))
175    }
176
177    /// Formats this hash into base64.
178    pub fn to_base64(&self) -> String {
179        Base64Engine.encode(&self.hash[..])
180    }
181
182    /// Formats this hash into hexadecimal.
183    pub fn to_hex(&self) -> String {
184        self.hash
185            .iter()
186            .map(|byte| format!("{:02x}", byte))
187            .collect::<Vec<_>>()
188            .join("")
189    }
190
191    /// Formats this hash into colon-separated hexadecimal.
192    pub fn to_colon_separated_hex(&self) -> String {
193        self.hash
194            .iter()
195            .map(|byte| format!("{:02x}", byte))
196            .collect::<Vec<_>>()
197            .join(":")
198    }
199}
200
201/// Helper for parsing and serialising a SHA-1 attribute.
202#[derive(Debug, Clone, PartialEq)]
203pub struct Sha1HexAttribute(Hash);
204
205impl FromStr for Sha1HexAttribute {
206    type Err = ParseIntError;
207
208    fn from_str(hex: &str) -> Result<Self, Self::Err> {
209        let hash = Hash::from_hex(Algo::Sha_1, hex)?;
210        Ok(Sha1HexAttribute(hash))
211    }
212}
213
214impl FromXmlText for Sha1HexAttribute {
215    fn from_xml_text(s: String) -> Result<Self, xso::error::Error> {
216        Self::from_str(&s).map_err(xso::error::Error::text_parse_error)
217    }
218}
219
220impl AsXmlText for Sha1HexAttribute {
221    fn as_xml_text(&self) -> Result<Cow<'_, str>, xso::error::Error> {
222        Ok(Cow::Owned(self.to_hex()))
223    }
224}
225
226impl IntoAttributeValue for Sha1HexAttribute {
227    fn into_attribute_value(self) -> Option<String> {
228        Some(self.to_hex())
229    }
230}
231
232impl DerefMut for Sha1HexAttribute {
233    fn deref_mut(&mut self) -> &mut Self::Target {
234        &mut self.0
235    }
236}
237
238impl Deref for Sha1HexAttribute {
239    type Target = Hash;
240
241    fn deref(&self) -> &Self::Target {
242        &self.0
243    }
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249    use minidom::Element;
250    use xso::error::FromElementError;
251
252    #[cfg(target_pointer_width = "32")]
253    #[test]
254    fn test_size() {
255        assert_size!(Algo, 12);
256        assert_size!(Hash, 24);
257    }
258
259    #[cfg(target_pointer_width = "64")]
260    #[test]
261    fn test_size() {
262        assert_size!(Algo, 24);
263        assert_size!(Hash, 48);
264    }
265
266    #[test]
267    fn test_simple() {
268        let elem: Element = "<hash xmlns='urn:xmpp:hashes:2' algo='sha-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>".parse().unwrap();
269        let hash = Hash::try_from(elem).unwrap();
270        assert_eq!(hash.algo, Algo::Sha_256);
271        assert_eq!(
272            hash.hash,
273            Base64Engine
274                .decode("2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=")
275                .unwrap()
276        );
277    }
278
279    #[test]
280    fn value_serialisation() {
281        let elem: Element = "<hash xmlns='urn:xmpp:hashes:2' algo='sha-256'>2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU=</hash>".parse().unwrap();
282        let hash = Hash::try_from(elem).unwrap();
283        assert_eq!(
284            hash.to_base64(),
285            "2XarmwTlNxDAMkvymloX3S5+VbylNrJt/l5QyPa+YoU="
286        );
287        assert_eq!(
288            hash.to_hex(),
289            "d976ab9b04e53710c0324bf29a5a17dd2e7e55bca536b26dfe5e50c8f6be6285"
290        );
291        assert_eq!(hash.to_colon_separated_hex(), "d9:76:ab:9b:04:e5:37:10:c0:32:4b:f2:9a:5a:17:dd:2e:7e:55:bc:a5:36:b2:6d:fe:5e:50:c8:f6:be:62:85");
292    }
293
294    #[test]
295    fn test_unknown() {
296        let elem: Element = "<replace xmlns='urn:xmpp:message-correct:0'/>"
297            .parse()
298            .unwrap();
299        let error = Hash::try_from(elem.clone()).unwrap_err();
300        let returned_elem = match error {
301            FromElementError::Mismatch(elem) => elem,
302            _ => panic!(),
303        };
304        assert_eq!(elem, returned_elem);
305    }
306
307    #[test]
308    #[cfg_attr(feature = "disable-validation", should_panic = "Result::unwrap_err")]
309    fn test_invalid_child() {
310        let elem: Element = "<hash xmlns='urn:xmpp:hashes:2' algo='sha-1'><coucou/></hash>"
311            .parse()
312            .unwrap();
313        let error = Hash::try_from(elem).unwrap_err();
314        let message = match error {
315            FromElementError::Invalid(Error::Other(string)) => string,
316            _ => panic!(),
317        };
318        assert_eq!(message, "Unknown child in Hash element.");
319    }
320}
xmpp_parsers/hashes.rs

xmpp_parsers/
hashes.rs
