Skip to main content

spodes_rs/classes/
security_setup.rs

1use crate::interface::InterfaceClass;
2use crate::obis::ObisCode;
3use crate::types::attrs::Certificate;
4use crate::types::{BerError, CosemDataType};
5use serde::{Deserialize, Serialize};
6use std::any::Any;
7use std::collections::BTreeMap;
8
9/// Symmetric key identifiers used by `key_transfer` (IEC 62056-6-2 §4.4.7.3.2).
10pub mod key_id {
11    /// Global unicast encryption key (GUEK).
12    pub const GLOBAL_UNICAST_ENCRYPTION: u8 = 0;
13    /// Global broadcast encryption key (GBEK).
14    pub const GLOBAL_BROADCAST_ENCRYPTION: u8 = 1;
15    /// Authentication key (AK).
16    pub const AUTHENTICATION: u8 = 2;
17    /// Master key / key encrypting key (KEK).
18    pub const MASTER: u8 = 3;
19}
20
21/// Configuration structure used to build a [`SecuritySetup`] object.
22#[derive(Clone, Serialize, Deserialize, Debug)]
23pub struct SecuritySetupConfig {
24    /// Attribute 1: the object's logical name (OBIS code).
25    pub logical_name: ObisCode,
26    /// Class version: 0 or 1. Version 1 adds the `certificates` attribute and the
27    /// PKI/ECDH methods.
28    pub version: u8,
29    /// Attribute 2: security policy (enum). See IEC 62056-6-2 §4.4.7.2.2.
30    pub security_policy: u8,
31    /// Attribute 3: security suite (enum). 0 = AES-GCM-128 with AES-128 key wrap.
32    pub security_suite: u8,
33    /// Attribute 4: client system title (octet-string).
34    pub client_system_title: Vec<u8>,
35    /// Attribute 5: server system title (octet-string).
36    pub server_system_title: Vec<u8>,
37    /// Attribute 6: certificates (array). Empty for security suite 0.
38    pub certificates: Vec<Certificate>,
39}
40
41/// `Security setup` interface class (class_id = 64) per IEC 62056-6-2 §4.4.7.
42/// Holds the security policy, suite, system titles and certificates, and manages
43/// the server's symmetric keys.
44///
45/// Both versions are supported:
46/// * version 0 — attributes 1..5, methods `security_activate` and
47///   `global_key_transfer`;
48/// * version 1 — attributes 1..6 (adds `certificates`), methods 1..8.
49///
50/// Only the mechanisms required by security suite 0 (AES-GCM-128) are
51/// implemented: `security_activate` and the key transfer method. The PKI/ECDH
52/// methods (`key_agreement`, `generate_key_pair`, certificate handling) belong
53/// to suites 1 and 2 and return an unsupported error here.
54#[derive(Clone, Serialize, Deserialize, Debug)]
55pub struct SecuritySetup {
56    version: u8,
57    logical_name: ObisCode,
58    security_policy: u8,
59    security_suite: u8,
60    client_system_title: Vec<u8>,
61    server_system_title: Vec<u8>,
62    certificates: Vec<Certificate>,
63    /// Installed symmetric keys, indexed by `key_id`. Transient security
64    /// material, not exposed as a COSEM attribute.
65    #[serde(skip)]
66    keys: BTreeMap<u8, Vec<u8>>,
67}
68
69impl SecuritySetup {
70    /// Builds a new [`SecuritySetup`] from its configuration.
71    pub fn new(config: SecuritySetupConfig) -> Self {
72        SecuritySetup {
73            version: config.version,
74            logical_name: config.logical_name,
75            security_policy: config.security_policy,
76            security_suite: config.security_suite,
77            client_system_title: config.client_system_title,
78            server_system_title: config.server_system_title,
79            certificates: config.certificates,
80            keys: BTreeMap::new(),
81        }
82    }
83
84    /// Returns the installed key for `key_id`, if any.
85    pub fn key(&self, key_id: u8) -> Option<&Vec<u8>> {
86        self.keys.get(&key_id)
87    }
88
89    /// Method 1: `security_activate` — activates and strengthens the security
90    /// policy (IEC 62056-6-2 §4.4.7.3.1). Strengthening is one-way: a value
91    /// weaker than the current policy is rejected.
92    fn security_activate(&mut self, data: &CosemDataType) -> Result<CosemDataType, String> {
93        let &CosemDataType::Enum(new_policy) = data else {
94            return Err("security_activate expects an enum".to_string());
95        };
96        if new_policy < self.security_policy {
97            return Err("security policy cannot be weakened".to_string());
98        }
99        self.security_policy = new_policy;
100        Ok(CosemDataType::Null)
101    }
102
103    /// Method 2: `key_transfer` — installs one or more symmetric keys
104    /// (IEC 62056-6-2 §4.4.7.3.2). The parameter is an array of
105    /// `key_transfer_data ::= structure { key_id: enum, key_wrapped: octet-string }`.
106    ///
107    /// The keys are stored as received. Unwrapping (AES key unwrap with the KEK)
108    /// is not performed here, since the master key management belongs to the
109    /// ciphering layer, which is out of scope for this data-model class.
110    fn key_transfer(&mut self, data: CosemDataType) -> Result<CosemDataType, String> {
111        let CosemDataType::Array(entries) = data else {
112            return Err("key_transfer expects an array of key_transfer_data".to_string());
113        };
114        let mut staged = BTreeMap::new();
115        for entry in &entries {
116            let CosemDataType::Structure(fields) = entry else {
117                return Err("key_transfer_data must be a structure".to_string());
118            };
119            if fields.len() != 2 {
120                return Err("key_transfer_data must hold key_id and key_wrapped".to_string());
121            }
122            let key_id = match &fields[0] {
123                CosemDataType::Enum(id) => *id,
124                _ => return Err("key_id must be an enum".to_string()),
125            };
126            let key = match &fields[1] {
127                CosemDataType::OctetString(bytes) => bytes.clone(),
128                _ => return Err("key_wrapped must be an octet-string".to_string()),
129            };
130            staged.insert(key_id, key);
131        }
132        // Apply atomically only after every entry has been validated.
133        self.keys.extend(staged);
134        Ok(CosemDataType::Null)
135    }
136}
137
138impl InterfaceClass for SecuritySetup {
139    fn class_id(&self) -> u16 {
140        64
141    }
142
143    fn version(&self) -> u8 {
144        self.version
145    }
146
147    fn logical_name(&self) -> &ObisCode {
148        &self.logical_name
149    }
150
151    fn attributes(&self) -> Vec<(u8, CosemDataType)> {
152        // Attributes 1..5 are common to both versions.
153        let mut attrs = vec![
154            (1, CosemDataType::OctetString(self.logical_name.to_bytes())),
155            (2, CosemDataType::Enum(self.security_policy)),
156            (3, CosemDataType::Enum(self.security_suite)),
157            (4, CosemDataType::OctetString(self.client_system_title.clone())),
158            (5, CosemDataType::OctetString(self.server_system_title.clone())),
159        ];
160        // The `certificates` attribute was added in version 1.
161        if self.version >= 1 {
162            attrs.push((
163                6,
164                CosemDataType::Array(self.certificates.iter().map(|c| CosemDataType::from(c.clone())).collect()),
165            ));
166        }
167        attrs
168    }
169
170    fn methods(&self) -> Vec<(u8, String)> {
171        // Method identifiers per IEC 62056-6-2 §4.4.7.1 / §5.3.8.1.
172        if self.version >= 1 {
173            vec![
174                (1, "security_activate".to_string()),
175                (2, "key_transfer".to_string()),
176                (3, "key_agreement".to_string()),
177                (4, "generate_key_pair".to_string()),
178                (5, "generate_certificate_request".to_string()),
179                (6, "import_certificate".to_string()),
180                (7, "export_certificate".to_string()),
181                (8, "remove_certificate".to_string()),
182            ]
183        } else {
184            // Version 0 has only these two methods.
185            vec![(1, "security_activate".to_string()), (2, "global_key_transfer".to_string())]
186        }
187    }
188
189    fn serialize_ber(&self, buf: &mut Vec<u8>) -> Result<(), BerError> {
190        let mut seq_buf = Vec::new();
191        CosemDataType::LongUnsigned(self.class_id()).serialize_ber(&mut seq_buf)?;
192        for (_, attr) in self.attributes() {
193            attr.serialize_ber(&mut seq_buf)?;
194        }
195        buf.push(0x02); // structure [2]
196        write_length(1 + self.attributes().len(), buf); // length = element count
197        buf.extend_from_slice(&seq_buf);
198        Ok(())
199    }
200
201    fn deserialize_ber(&mut self, data: &[u8]) -> Result<(), BerError> {
202        let (tlv, rest) = CosemDataType::deserialize_ber(data)?;
203        if !rest.is_empty() {
204            return Err(BerError::InvalidTag);
205        }
206        let CosemDataType::Structure(seq) = tlv else {
207            return Err(BerError::InvalidTag);
208        };
209        // The element count (class_id + attributes) identifies the version:
210        // 6 → v0, 7 → v1.
211        self.version = match seq.len() {
212            6 => 0,
213            7 => 1,
214            _ => return Err(BerError::InvalidLength),
215        };
216        if let CosemDataType::LongUnsigned(class_id) = seq[0] {
217            if class_id != self.class_id() {
218                return Err(BerError::InvalidValue);
219            }
220        } else {
221            return Err(BerError::InvalidTag);
222        }
223        if let CosemDataType::OctetString(obis) = &seq[1] {
224            if obis.len() == 6 {
225                self.logical_name = ObisCode::new(obis[0], obis[1], obis[2], obis[3], obis[4], obis[5]);
226            } else {
227                return Err(BerError::InvalidLength);
228            }
229        } else {
230            return Err(BerError::InvalidTag);
231        }
232        self.security_policy = match seq[2] {
233            CosemDataType::Enum(v) => v,
234            _ => return Err(BerError::InvalidTag),
235        };
236        self.security_suite = match seq[3] {
237            CosemDataType::Enum(v) => v,
238            _ => return Err(BerError::InvalidTag),
239        };
240        self.client_system_title = match &seq[4] {
241            CosemDataType::OctetString(bytes) => bytes.clone(),
242            _ => return Err(BerError::InvalidTag),
243        };
244        self.server_system_title = match &seq[5] {
245            CosemDataType::OctetString(bytes) => bytes.clone(),
246            _ => return Err(BerError::InvalidTag),
247        };
248        if self.version >= 1 {
249            self.certificates = match &seq[6] {
250                CosemDataType::Array(list) => list
251                    .iter()
252                    .map(Certificate::try_from)
253                    .collect::<Result<Vec<_>, _>>()
254                    .map_err(|_| BerError::InvalidValue)?,
255                _ => return Err(BerError::InvalidTag),
256            };
257        }
258        Ok(())
259    }
260
261    fn set_attribute(&mut self, attribute_id: u8, value: CosemDataType) -> Result<(), String> {
262        match attribute_id {
263            2 => match value {
264                CosemDataType::Enum(v) => {
265                    self.security_policy = v;
266                    Ok(())
267                }
268                _ => Err("security_policy must be enum".into()),
269            },
270            3 => match value {
271                CosemDataType::Enum(v) => {
272                    self.security_suite = v;
273                    Ok(())
274                }
275                _ => Err("security_suite must be enum".into()),
276            },
277            4 => match value {
278                CosemDataType::OctetString(v) => {
279                    self.client_system_title = v;
280                    Ok(())
281                }
282                _ => Err("client_system_title must be octet-string".into()),
283            },
284            5 => match value {
285                CosemDataType::OctetString(v) => {
286                    self.server_system_title = v;
287                    Ok(())
288                }
289                _ => Err("server_system_title must be octet-string".into()),
290            },
291            _ => Err(format!("SecuritySetup attribute {attribute_id} is not writable")),
292        }
293    }
294
295    fn invoke_method(&mut self, method_id: u8, params: Option<CosemDataType>) -> Result<CosemDataType, String> {
296        let params = params.ok_or("Missing method parameter")?;
297        match method_id {
298            1 => self.security_activate(&params),
299            2 => self.key_transfer(params),
300            3..=8 if self.version >= 1 => {
301                Err(format!("Method {method_id} requires security suite 1 or 2 (PKI/ECDH); not supported for suite 0"))
302            }
303            _ => Err(format!("Method {} not supported for Security setup version {}", method_id, self.version)),
304        }
305    }
306
307    fn as_any(&self) -> &dyn Any {
308        self
309    }
310}
311
312/// Writes a BER length octet (short or long form).
313#[allow(clippy::cast_possible_truncation)] // length < 128 and num_octets in 1..=8 always fit u8
314fn write_length(length: usize, buf: &mut Vec<u8>) {
315    if length < 128 {
316        buf.push(length as u8);
317    } else {
318        let bytes = (length as u64).to_be_bytes();
319        let first_non_zero = bytes.iter().position(|&b| b != 0).unwrap_or(7);
320        let num_octets = 8 - first_non_zero;
321        buf.push(0x80 | num_octets as u8);
322        buf.extend_from_slice(&bytes[first_non_zero..]);
323    }
324}
325
326#[cfg(test)]
327mod tests {
328    use super::*;
329
330    fn sample_versioned(version: u8) -> SecuritySetup {
331        SecuritySetup::new(SecuritySetupConfig {
332            logical_name: ObisCode::new(0, 0, 43, 0, 0, 255),
333            version,
334            security_policy: 0,
335            security_suite: 0,
336            client_system_title: b"CLIENT01".to_vec(),
337            server_system_title: b"SERVER01".to_vec(),
338            certificates: vec![],
339        })
340    }
341
342    fn sample() -> SecuritySetup {
343        sample_versioned(1)
344    }
345
346    #[test]
347    fn attribute_and_method_counts_per_version() {
348        let expected = [(0u8, 5usize, 2usize), (1, 6, 8)];
349        for (version, attr_count, method_count) in expected {
350            let obj = sample_versioned(version);
351            assert_eq!(obj.class_id(), 64);
352            assert_eq!(obj.version(), version);
353            assert_eq!(obj.attributes().len(), attr_count, "attrs for v{version}");
354            assert_eq!(obj.methods().len(), method_count, "methods for v{version}");
355        }
356    }
357
358    #[test]
359    fn round_trip_all_versions() {
360        for version in 0..=1u8 {
361            let obj = sample_versioned(version);
362            let mut buf = Vec::new();
363            obj.serialize_ber(&mut buf).unwrap();
364            let mut decoded = sample_versioned(1 - version);
365            decoded.deserialize_ber(&buf).unwrap();
366            assert_eq!(decoded.version(), version);
367            assert_eq!(decoded.attributes(), obj.attributes());
368        }
369    }
370
371    #[test]
372    fn security_activate_only_strengthens() {
373        let mut obj = sample();
374        obj.security_policy = 1;
375        // Stronger policy is accepted.
376        obj.invoke_method(1, Some(CosemDataType::Enum(3))).unwrap();
377        assert_eq!(obj.attributes()[1].1, CosemDataType::Enum(3));
378        // Weaker policy is rejected and leaves the attribute unchanged.
379        assert!(obj.invoke_method(1, Some(CosemDataType::Enum(1))).is_err());
380        assert_eq!(obj.attributes()[1].1, CosemDataType::Enum(3));
381    }
382
383    #[test]
384    fn key_transfer_installs_keys() {
385        let mut obj = sample();
386        let data = CosemDataType::Array(vec![
387            CosemDataType::Structure(vec![
388                CosemDataType::Enum(key_id::GLOBAL_UNICAST_ENCRYPTION),
389                CosemDataType::OctetString(vec![0x01; 16]),
390            ]),
391            CosemDataType::Structure(vec![
392                CosemDataType::Enum(key_id::AUTHENTICATION),
393                CosemDataType::OctetString(vec![0x02; 16]),
394            ]),
395        ]);
396        obj.invoke_method(2, Some(data)).unwrap();
397        assert_eq!(obj.key(key_id::GLOBAL_UNICAST_ENCRYPTION), Some(&vec![0x01; 16]));
398        assert_eq!(obj.key(key_id::AUTHENTICATION), Some(&vec![0x02; 16]));
399    }
400
401    #[test]
402    fn pki_methods_unsupported_for_suite0() {
403        let mut obj = sample();
404        for method_id in 3..=8 {
405            assert!(obj.invoke_method(method_id, Some(CosemDataType::Null)).is_err());
406        }
407    }
408}