sip_header/
security.rs

1//! SIP Security mechanism parser (RFC 3329).
2//!
3//! Used by Security-Client, Security-Server, and Security-Verify headers.
4
5use std::fmt;
6
7/// A parsed security mechanism entry: `mechanism-name *(SEMI mech-params)`.
8#[derive(Debug, Clone, PartialEq, Eq)]
9#[non_exhaustive]
10pub struct SipSecurityMechanism {
11    mechanism: String,
12    params: Vec<(String, Option<String>)>,
13}
14
15impl SipSecurityMechanism {
16    /// The mechanism name (e.g. `"digest"`, `"tls"`, `"ipsec-ike"`).
17    pub fn mechanism(&self) -> &str {
18        &self.mechanism
19    }
20
21    /// All parameters as `(key, optional_value)` pairs.
22    pub fn params(&self) -> &[(String, Option<String>)] {
23        &self.params
24    }
25
26    /// Look up a parameter by key (case-insensitive).
27    pub fn param(&self, key: &str) -> Option<Option<&str>> {
28        self.params
29            .iter()
30            .find(|(k, _)| k.eq_ignore_ascii_case(key))
31            .map(|(_, v)| v.as_deref())
32    }
33
34    /// The `q` preference value, if present.
35    pub fn q(&self) -> Option<&str> {
36        self.param("q")
37            .flatten()
38    }
39
40    /// The `d-alg` parameter, if present.
41    pub fn d_alg(&self) -> Option<&str> {
42        self.param("d-alg")
43            .flatten()
44    }
45
46    /// The `d-qop` parameter, if present.
47    pub fn d_qop(&self) -> Option<&str> {
48        self.param("d-qop")
49            .flatten()
50    }
51}
52
53impl fmt::Display for SipSecurityMechanism {
54    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
55        write!(f, "{}", self.mechanism)?;
56        for (key, value) in &self.params {
57            match value {
58                Some(v) => write!(f, ";{key}={v}")?,
59                None => write!(f, ";{key}")?,
60            }
61        }
62        Ok(())
63    }
64}
65
66/// Errors from parsing a security mechanism header value.
67#[derive(Debug, Clone, PartialEq, Eq)]
68#[non_exhaustive]
69pub enum SipSecurityError {
70    /// The input string was empty or whitespace-only.
71    Empty,
72    /// A mechanism entry could not be parsed.
73    InvalidFormat(String),
74}
75
76impl fmt::Display for SipSecurityError {
77    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
78        match self {
79            Self::Empty => write!(f, "empty security mechanism value"),
80            Self::InvalidFormat(raw) => {
81                write!(f, "invalid security mechanism: {raw}")
82            }
83        }
84    }
85}
86
87impl std::error::Error for SipSecurityError {}
88
89fn parse_mechanism(raw: &str) -> Result<SipSecurityMechanism, SipSecurityError> {
90    let raw = raw.trim();
91    if raw.is_empty() {
92        return Err(SipSecurityError::InvalidFormat(raw.to_string()));
93    }
94
95    let (mechanism_part, params_part) = match raw.split_once(';') {
96        Some((m, p)) => (m.trim(), Some(p)),
97        None => (raw, None),
98    };
99
100    if mechanism_part.is_empty() {
101        return Err(SipSecurityError::InvalidFormat(raw.to_string()));
102    }
103
104    let mechanism = mechanism_part.to_ascii_lowercase();
105    let mut params = Vec::new();
106
107    if let Some(params_str) = params_part {
108        for segment in params_str.split(';') {
109            let segment = segment.trim();
110            if segment.is_empty() {
111                continue;
112            }
113            if let Some((key, value)) = segment.split_once('=') {
114                params.push((
115                    key.trim()
116                        .to_ascii_lowercase(),
117                    Some(
118                        value
119                            .trim()
120                            .trim_matches('"')
121                            .to_string(),
122                    ),
123                ));
124            } else {
125                params.push((segment.to_ascii_lowercase(), None));
126            }
127        }
128    }
129
130    Ok(SipSecurityMechanism { mechanism, params })
131}
132
133/// Parsed security mechanism header value.
134#[derive(Debug, Clone, PartialEq, Eq)]
135#[non_exhaustive]
136pub struct SipSecurity(Vec<SipSecurityMechanism>);
137
138impl SipSecurity {
139    /// Parse a comma-separated security mechanism value.
140    pub fn parse(raw: &str) -> Result<Self, SipSecurityError> {
141        let raw = raw.trim();
142        if raw.is_empty() {
143            return Err(SipSecurityError::Empty);
144        }
145        let entries: Vec<_> = crate::split_comma_entries(raw)
146            .into_iter()
147            .map(parse_mechanism)
148            .collect::<Result<_, _>>()?;
149        if entries.is_empty() {
150            return Err(SipSecurityError::Empty);
151        }
152        Ok(Self(entries))
153    }
154
155    /// The parsed entries as a slice.
156    pub fn entries(&self) -> &[SipSecurityMechanism] {
157        &self.0
158    }
159
160    /// Consume self and return entries as a `Vec`.
161    pub fn into_entries(self) -> Vec<SipSecurityMechanism> {
162        self.0
163    }
164
165    /// Number of entries.
166    pub fn len(&self) -> usize {
167        self.0
168            .len()
169    }
170
171    /// Returns `true` if there are no entries.
172    pub fn is_empty(&self) -> bool {
173        self.0
174            .is_empty()
175    }
176}
177
178impl fmt::Display for SipSecurity {
179    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
180        crate::fmt_joined(f, &self.0, ", ")
181    }
182}
183
184impl_from_str_via_parse!(SipSecurity, SipSecurityError);
185
186impl<'a> IntoIterator for &'a SipSecurity {
187    type Item = &'a SipSecurityMechanism;
188    type IntoIter = std::slice::Iter<'a, SipSecurityMechanism>;
189
190    fn into_iter(self) -> Self::IntoIter {
191        self.0
192            .iter()
193    }
194}
195
196impl IntoIterator for SipSecurity {
197    type Item = SipSecurityMechanism;
198    type IntoIter = std::vec::IntoIter<SipSecurityMechanism>;
199
200    fn into_iter(self) -> Self::IntoIter {
201        self.0
202            .into_iter()
203    }
204}
205
206#[cfg(test)]
207mod tests {
208    use super::*;
209
210    #[test]
211    fn single_mechanism() {
212        let sec = SipSecurity::parse("digest;d-qop=auth-int;q=0.1").unwrap();
213        assert_eq!(sec.len(), 1);
214        assert_eq!(sec.entries()[0].mechanism(), "digest");
215        assert_eq!(sec.entries()[0].d_qop(), Some("auth-int"));
216        assert_eq!(sec.entries()[0].q(), Some("0.1"));
217    }
218
219    #[test]
220    fn multiple_mechanisms() {
221        let sec = SipSecurity::parse("tls;q=0.2, digest;d-qop=auth;q=0.1").unwrap();
222        assert_eq!(sec.len(), 2);
223        assert_eq!(sec.entries()[0].mechanism(), "tls");
224        assert_eq!(sec.entries()[1].mechanism(), "digest");
225    }
226
227    #[test]
228    fn mechanism_no_params() {
229        let sec = SipSecurity::parse("tls").unwrap();
230        assert_eq!(sec.len(), 1);
231        assert_eq!(sec.entries()[0].mechanism(), "tls");
232        assert!(sec.entries()[0]
233            .params()
234            .is_empty());
235    }
236
237    #[test]
238    fn empty_input() {
239        assert!(matches!(
240            SipSecurity::parse(""),
241            Err(SipSecurityError::Empty)
242        ));
243    }
244
245    #[test]
246    fn display_roundtrip() {
247        let raw = "digest;d-qop=auth;q=0.1";
248        let sec = SipSecurity::parse(raw).unwrap();
249        assert_eq!(sec.to_string(), raw);
250    }
251
252    #[test]
253    fn from_str() {
254        let sec: SipSecurity = "tls;q=0.2"
255            .parse()
256            .unwrap();
257        assert_eq!(sec.len(), 1);
258    }
259
260    #[test]
261    fn d_alg_param() {
262        let sec = SipSecurity::parse("digest;d-alg=MD5;d-qop=auth").unwrap();
263        assert_eq!(sec.entries()[0].d_alg(), Some("MD5"));
264    }
265}
sip_header/security.rs

sip_header/
security.rs
