Skip to main content

spodes_rs/types/
mod.rs

1pub mod attrs;
2
3use serde::{Deserialize, Serialize};
4use std::fmt;
5
6/// A COSEM common data type (IEC 62056-6-2, Table 3), with A-XDR (BER)
7/// serialization via [`CosemDataType::serialize_ber`] /
8/// [`CosemDataType::deserialize_ber`].
9#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
10pub enum CosemDataType {
11    /// `null-data` (tag 0).
12    Null,
13    /// `array` (tag 1) — a sequence of same-typed elements.
14    Array(Vec<CosemDataType>),
15    /// `structure` (tag 2) — a sequence of (possibly differently typed) elements.
16    Structure(Vec<CosemDataType>),
17    /// `boolean` (tag 3).
18    Boolean(bool),
19    /// `integer` — signed 8-bit (tag 15).
20    Integer(i8),
21    /// `long` — signed 16-bit (tag 16).
22    Long(i16),
23    /// `unsigned` — unsigned 8-bit (tag 17).
24    Unsigned(u8),
25    /// `long-unsigned` — unsigned 16-bit (tag 18).
26    LongUnsigned(u16),
27    /// `double-long` — signed 32-bit (tag 5).
28    DoubleLong(i32),
29    /// `double-long-unsigned` — unsigned 32-bit (tag 6).
30    DoubleLongUnsigned(u32),
31    /// `octet-string` (tag 9).
32    OctetString(Vec<u8>),
33    /// `date-time` (tag 25) — a 12-octet date-time value.
34    DateTime(Vec<u8>),
35    /// `bit-string` (tag 4) — held as raw octets.
36    BitString(Vec<u8>),
37    /// `enum` — an enumerated 8-bit value (tag 22).
38    Enum(u8),
39}
40
41/// An error while encoding or decoding a [`CosemDataType`] in BER.
42#[derive(Debug, PartialEq)]
43pub enum BerError {
44    /// The tag octet was not a recognized COSEM data type.
45    InvalidTag,
46    /// The value ended before all declared octets were present.
47    InvalidLength,
48    /// A value did not conform to its type.
49    InvalidValue,
50}
51
52impl CosemDataType {
53    /// Appends the A-XDR (BER) encoding of this value to `buf`.
54    pub fn serialize_ber(&self, buf: &mut Vec<u8>) -> Result<(), BerError> {
55        // A-XDR encoding of the common data types (IEC 62056-6-2, Table 3).
56        // Tags are the one-octet values from the table; fixed scalar types and
57        // enums are encoded as [tag][value] with no length octet; array/structure
58        // carry a length equal to the ELEMENT COUNT (not the byte count).
59        match self {
60            CosemDataType::Null => {
61                buf.push(0x00); // null-data [0]: no length and no content
62                Ok(())
63            }
64            CosemDataType::Array(items) => {
65                buf.push(0x01); // array [1]
66                write_length(items.len(), buf); // length = element count
67                for item in items {
68                    item.serialize_ber(buf)?;
69                }
70                Ok(())
71            }
72            CosemDataType::Structure(items) => {
73                buf.push(0x02); // structure [2]
74                write_length(items.len(), buf); // length = element count
75                for item in items {
76                    item.serialize_ber(buf)?;
77                }
78                Ok(())
79            }
80            CosemDataType::Boolean(b) => {
81                buf.push(0x03); // boolean [3]
82                buf.push(if *b { 0x01 } else { 0x00 });
83                Ok(())
84            }
85            CosemDataType::Integer(i) => {
86                buf.push(0x0F); // integer [15]
87                                // Raw octet round-tripped bit-for-bit via `as i8` on decode.
88                #[allow(clippy::cast_sign_loss)]
89                buf.push(*i as u8);
90                Ok(())
91            }
92            CosemDataType::Long(i) => {
93                buf.push(0x10); // long [16]
94                buf.extend_from_slice(&i.to_be_bytes());
95                Ok(())
96            }
97            CosemDataType::Unsigned(u) => {
98                buf.push(0x11); // unsigned [17]
99                buf.push(*u);
100                Ok(())
101            }
102            CosemDataType::LongUnsigned(u) => {
103                buf.push(0x12); // long-unsigned [18]
104                buf.extend_from_slice(&u.to_be_bytes());
105                Ok(())
106            }
107            CosemDataType::DoubleLong(i) => {
108                buf.push(0x05); // double-long [5]
109                buf.extend_from_slice(&i.to_be_bytes());
110                Ok(())
111            }
112            CosemDataType::DoubleLongUnsigned(u) => {
113                buf.push(0x06); // double-long-unsigned [6]
114                buf.extend_from_slice(&u.to_be_bytes());
115                Ok(())
116            }
117            CosemDataType::OctetString(s) => {
118                buf.push(0x09); // octet-string [9]
119                write_length(s.len(), buf);
120                buf.extend_from_slice(s);
121                Ok(())
122            }
123            CosemDataType::DateTime(dt) => {
124                buf.push(0x19); // date-time [25]: octet-string SIZE(12) with a length octet
125                write_length(dt.len(), buf);
126                buf.extend_from_slice(dt);
127                Ok(())
128            }
129            CosemDataType::BitString(s) => {
130                buf.push(0x04); // bit-string [4]
131                                // NB: in A-XDR the bit-string length is given in BITS; here the
132                                // byte count is stored, since the type model holds a raw Vec<u8>.
133                write_length(s.len(), buf);
134                buf.extend_from_slice(s);
135                Ok(())
136            }
137            CosemDataType::Enum(e) => {
138                buf.push(0x16); // enum [22]
139                buf.push(*e);
140                Ok(())
141            }
142        }
143    }
144
145    /// Decodes one A-XDR (BER) value from `data`, returning it and the
146    /// unconsumed remainder.
147    pub fn deserialize_ber(data: &[u8]) -> Result<(Self, &[u8]), BerError> {
148        if data.is_empty() {
149            return Err(BerError::InvalidTag);
150        }
151        match data[0] {
152            0x00 => Ok((CosemDataType::Null, &data[1..])),
153            0x01 => {
154                let (count, mut rest) = read_length(&data[1..])?;
155                let mut items = Vec::with_capacity(count);
156                for _ in 0..count {
157                    let (item, next) = CosemDataType::deserialize_ber(rest)?;
158                    items.push(item);
159                    rest = next;
160                }
161                Ok((CosemDataType::Array(items), rest))
162            }
163            0x02 => {
164                let (count, mut rest) = read_length(&data[1..])?;
165                let mut items = Vec::with_capacity(count);
166                for _ in 0..count {
167                    let (item, next) = CosemDataType::deserialize_ber(rest)?;
168                    items.push(item);
169                    rest = next;
170                }
171                Ok((CosemDataType::Structure(items), rest))
172            }
173            0x03 => {
174                if data.len() >= 2 {
175                    Ok((CosemDataType::Boolean(data[1] != 0), &data[2..]))
176                } else {
177                    Err(BerError::InvalidLength)
178                }
179            }
180            0x0F => {
181                if data.len() >= 2 {
182                    // Raw octet round-tripped bit-for-bit from `as u8` on encode.
183                    #[allow(clippy::cast_possible_wrap)]
184                    let value = data[1] as i8;
185                    Ok((CosemDataType::Integer(value), &data[2..]))
186                } else {
187                    Err(BerError::InvalidLength)
188                }
189            }
190            0x10 => {
191                if data.len() >= 3 {
192                    let value = i16::from_be_bytes([data[1], data[2]]);
193                    Ok((CosemDataType::Long(value), &data[3..]))
194                } else {
195                    Err(BerError::InvalidLength)
196                }
197            }
198            0x11 => {
199                if data.len() >= 2 {
200                    Ok((CosemDataType::Unsigned(data[1]), &data[2..]))
201                } else {
202                    Err(BerError::InvalidLength)
203                }
204            }
205            0x12 => {
206                if data.len() >= 3 {
207                    let value = u16::from_be_bytes([data[1], data[2]]);
208                    Ok((CosemDataType::LongUnsigned(value), &data[3..]))
209                } else {
210                    Err(BerError::InvalidLength)
211                }
212            }
213            0x05 => {
214                if data.len() >= 5 {
215                    let value = i32::from_be_bytes([data[1], data[2], data[3], data[4]]);
216                    Ok((CosemDataType::DoubleLong(value), &data[5..]))
217                } else {
218                    Err(BerError::InvalidLength)
219                }
220            }
221            0x06 => {
222                if data.len() >= 5 {
223                    let value = u32::from_be_bytes([data[1], data[2], data[3], data[4]]);
224                    Ok((CosemDataType::DoubleLongUnsigned(value), &data[5..]))
225                } else {
226                    Err(BerError::InvalidLength)
227                }
228            }
229            0x09 => {
230                let (len, rest) = read_length(&data[1..])?;
231                if rest.len() >= len {
232                    Ok((CosemDataType::OctetString(rest[..len].to_vec()), &rest[len..]))
233                } else {
234                    Err(BerError::InvalidLength)
235                }
236            }
237            0x19 => {
238                let (len, rest) = read_length(&data[1..])?;
239                if rest.len() >= len {
240                    Ok((CosemDataType::DateTime(rest[..len].to_vec()), &rest[len..]))
241                } else {
242                    Err(BerError::InvalidLength)
243                }
244            }
245            0x04 => {
246                let (len, rest) = read_length(&data[1..])?;
247                if rest.len() >= len {
248                    Ok((CosemDataType::BitString(rest[..len].to_vec()), &rest[len..]))
249                } else {
250                    Err(BerError::InvalidLength)
251                }
252            }
253            0x16 => {
254                if data.len() >= 2 {
255                    Ok((CosemDataType::Enum(data[1]), &data[2..]))
256                } else {
257                    Err(BerError::InvalidLength)
258                }
259            }
260            _ => Err(BerError::InvalidTag),
261        }
262    }
263}
264
265/// Writes a BER/A-XDR length octet (short or long form).
266#[allow(clippy::cast_possible_truncation)] // length < 128 and num_octets in 1..=8 always fit u8
267fn write_length(length: usize, buf: &mut Vec<u8>) {
268    if length < 128 {
269        buf.push(length as u8);
270    } else {
271        let bytes = (length as u64).to_be_bytes();
272        let first_non_zero = bytes.iter().position(|&b| b != 0).unwrap_or(7);
273        let num_octets = 8 - first_non_zero;
274        buf.push(0x80 | num_octets as u8);
275        buf.extend_from_slice(&bytes[first_non_zero..]);
276    }
277}
278
279fn read_length(data: &[u8]) -> Result<(usize, &[u8]), BerError> {
280    if data.is_empty() {
281        return Err(BerError::InvalidLength);
282    }
283    if data[0] & 0x80 == 0 {
284        Ok((data[0] as usize, &data[1..]))
285    } else {
286        let num_octets = (data[0] & 0x7F) as usize;
287        // Longer length fields would overflow on crafted input; 4 octets
288        // (lengths up to 2^32-1) are more than any DLMS PDU can carry.
289        if num_octets == 0 || num_octets > 4 || data.len() < num_octets + 1 {
290            return Err(BerError::InvalidLength);
291        }
292        let mut len: usize = 0;
293        for &b in &data[1..=num_octets] {
294            len = (len << 8) + b as usize;
295        }
296        let rest = &data[num_octets + 1..];
297        // A declared length beyond the remaining buffer is malformed; rejecting
298        // it here prevents oversized allocations from crafted headers.
299        if len > rest.len() {
300            return Err(BerError::InvalidLength);
301        }
302        Ok((len, rest))
303    }
304}
305
306impl fmt::Display for CosemDataType {
307    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
308        match self {
309            CosemDataType::Null => write!(f, "Null"),
310            CosemDataType::Array(items) => {
311                write!(f, "Array([")?;
312                for (i, item) in items.iter().enumerate() {
313                    if i > 0 {
314                        write!(f, ", ")?;
315                    }
316                    write!(f, "{item}")?;
317                }
318                write!(f, "])")
319            }
320            CosemDataType::Structure(items) => {
321                write!(f, "Structure([")?;
322                for (i, item) in items.iter().enumerate() {
323                    if i > 0 {
324                        write!(f, ", ")?;
325                    }
326                    write!(f, "{item}")?;
327                }
328                write!(f, "])")
329            }
330            CosemDataType::Boolean(b) => write!(f, "Boolean({b})"),
331            CosemDataType::Integer(i) => write!(f, "Integer({i})"),
332            CosemDataType::Long(i) => write!(f, "Long({i})"),
333            CosemDataType::Unsigned(u) => write!(f, "Unsigned({u})"),
334            CosemDataType::LongUnsigned(u) => write!(f, "LongUnsigned({u})"),
335            CosemDataType::DoubleLong(i) => write!(f, "DoubleLong({i})"),
336            CosemDataType::DoubleLongUnsigned(u) => write!(f, "DoubleLongUnsigned({u})"),
337            CosemDataType::OctetString(s) => write!(f, "OctetString({s:?})"),
338            CosemDataType::DateTime(dt) => write!(f, "DateTime({dt:?})"),
339            CosemDataType::BitString(s) => write!(f, "BitString({s:?})"),
340            CosemDataType::Enum(e) => write!(f, "Enum({e})"),
341        }
342    }
343}
344
345#[cfg(test)]
346mod tests {
347    use super::*;
348
349    fn enc(v: &CosemDataType) -> Vec<u8> {
350        let mut buf = Vec::new();
351        v.serialize_ber(&mut buf).unwrap();
352        buf
353    }
354
355    /// A crafted long-form length must not overflow or allocate: more than
356    /// 4 length octets, or a declared length beyond the buffer, is rejected.
357    #[test]
358    fn crafted_ber_length_is_rejected() {
359        // octet-string, long form with 9 length octets (would shift-overflow).
360        let crafted = [0x09, 0x89, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF];
361        assert!(CosemDataType::deserialize_ber(&crafted).is_err());
362        // octet-string declaring 0xFFFFFFFF octets with an empty body.
363        let oversized = [0x09, 0x84, 0xFF, 0xFF, 0xFF, 0xFF];
364        assert!(CosemDataType::deserialize_ber(&oversized).is_err());
365    }
366
367    /// Reference A-XDR vector from DLMS UA 1000-1 (context_name encoding example,
368    /// context_id(1)): a 7-element structure → 02 07 11 02 11 10 12 02 F4 11 05 11 08 11 01 11 01.
369    #[test]
370    fn axdr_reference_context_name() {
371        let s = CosemDataType::Structure(vec![
372            CosemDataType::Unsigned(2),
373            CosemDataType::Unsigned(16),
374            CosemDataType::LongUnsigned(756),
375            CosemDataType::Unsigned(5),
376            CosemDataType::Unsigned(8),
377            CosemDataType::Unsigned(1),
378            CosemDataType::Unsigned(1),
379        ]);
380        assert_eq!(
381            enc(&s),
382            vec![0x02, 0x07, 0x11, 0x02, 0x11, 0x10, 0x12, 0x02, 0xF4, 0x11, 0x05, 0x11, 0x08, 0x11, 0x01, 0x11, 0x01]
383        );
384    }
385
386    /// Simple-type tags per Table 3, and the absence of a length octet on scalars.
387    #[test]
388    fn axdr_scalar_tags() {
389        assert_eq!(enc(&CosemDataType::Null), vec![0x00]);
390        assert_eq!(enc(&CosemDataType::Boolean(true)), vec![0x03, 0x01]);
391        assert_eq!(enc(&CosemDataType::Integer(-1)), vec![0x0F, 0xFF]);
392        assert_eq!(enc(&CosemDataType::Long(-2)), vec![0x10, 0xFF, 0xFE]);
393        assert_eq!(enc(&CosemDataType::DoubleLong(1)), vec![0x05, 0x00, 0x00, 0x00, 0x01]);
394        assert_eq!(enc(&CosemDataType::DoubleLongUnsigned(1)), vec![0x06, 0x00, 0x00, 0x00, 0x01]);
395        assert_eq!(enc(&CosemDataType::Unsigned(5)), vec![0x11, 0x05]);
396        assert_eq!(enc(&CosemDataType::LongUnsigned(756)), vec![0x12, 0x02, 0xF4]);
397        assert_eq!(enc(&CosemDataType::Enum(3)), vec![0x16, 0x03]);
398        assert_eq!(enc(&CosemDataType::OctetString(vec![0xAB, 0xCD])), vec![0x09, 0x02, 0xAB, 0xCD]);
399        assert_eq!(enc(&CosemDataType::Array(vec![CosemDataType::Unsigned(1)])), vec![0x01, 0x01, 0x11, 0x01]);
400    }
401
402    #[test]
403    fn axdr_round_trip() {
404        let samples = vec![
405            CosemDataType::Null,
406            CosemDataType::Boolean(false),
407            CosemDataType::Integer(-128),
408            CosemDataType::Long(-32768),
409            CosemDataType::Unsigned(255),
410            CosemDataType::LongUnsigned(65535),
411            CosemDataType::DoubleLong(-1),
412            CosemDataType::DoubleLongUnsigned(4_000_000_000),
413            CosemDataType::Enum(7),
414            CosemDataType::OctetString(vec![1, 2, 3]),
415            CosemDataType::DateTime(vec![0x07, 0xE5, 0x05, 0x01, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]),
416            CosemDataType::Array(vec![CosemDataType::Unsigned(1), CosemDataType::Unsigned(2)]),
417            CosemDataType::Structure(vec![
418                CosemDataType::LongUnsigned(7),
419                CosemDataType::OctetString(vec![0, 0, 96, 1, 0, 255]),
420                CosemDataType::Array(vec![CosemDataType::Enum(1)]),
421            ]),
422        ];
423        for s in samples {
424            let bytes = enc(&s);
425            let (decoded, rest) = CosemDataType::deserialize_ber(&bytes).unwrap();
426            assert!(rest.is_empty(), "trailing bytes for {s:?}");
427            assert_eq!(decoded, s);
428        }
429    }
430}