Skip to main content

spodes_rs/security/
access_rights.rs

1//! Access rights model for DLMS/COSEM (IEC 62056-5-3, 5.3.7).
2//!
3//! The Association LN object holds an `object_list` that defines the visible
4//! COSEM objects and their access rights. Each object entry contains:
5//! - `class_id`, `version`, `logical_name` — object identification
6//! - `access_rights` — permissions for attributes and methods
7//!
8//! Access modes per IEC 62056-5-3:
9//! - Attribute: no_access(0), read_only(1), write_only(2), read_and_write(3),
10//!   authenticated_read_only(4), authenticated_write_only(5), authenticated_read_and_write(6)
11//! - Method: no_access(0), access(1), authenticated_access(2)
12
13/// Access mode for an attribute (IEC 62056-5-3, 5.3.7.2.2).
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum AttributeAccessMode {
16    /// No access to this attribute.
17    NoAccess = 0,
18    /// Read-only access.
19    ReadOnly = 1,
20    /// Write-only access.
21    WriteOnly = 2,
22    /// Read and write access.
23    ReadWrite = 3,
24    /// Authenticated read-only access.
25    AuthenticatedReadOnly = 4,
26    /// Authenticated write-only access.
27    AuthenticatedWriteOnly = 5,
28    /// Authenticated read and write access.
29    AuthenticatedReadWrite = 6,
30}
31
32impl AttributeAccessMode {
33    /// Parses an access mode from its numeric value.
34    pub fn from_u8(v: u8) -> Option<Self> {
35        match v {
36            0 => Some(Self::NoAccess),
37            1 => Some(Self::ReadOnly),
38            2 => Some(Self::WriteOnly),
39            3 => Some(Self::ReadWrite),
40            4 => Some(Self::AuthenticatedReadOnly),
41            5 => Some(Self::AuthenticatedWriteOnly),
42            6 => Some(Self::AuthenticatedReadWrite),
43            _ => None,
44        }
45    }
46
47    /// Whether this mode allows reading.
48    pub fn allows_read(&self) -> bool {
49        matches!(self, Self::ReadOnly | Self::ReadWrite | Self::AuthenticatedReadOnly | Self::AuthenticatedReadWrite)
50    }
51
52    /// Whether this mode allows writing.
53    pub fn allows_write(&self) -> bool {
54        matches!(self, Self::WriteOnly | Self::ReadWrite | Self::AuthenticatedWriteOnly | Self::AuthenticatedReadWrite)
55    }
56
57    /// Whether this mode requires authentication.
58    pub fn requires_auth(&self) -> bool {
59        matches!(self, Self::AuthenticatedReadOnly | Self::AuthenticatedWriteOnly | Self::AuthenticatedReadWrite)
60    }
61}
62
63/// Access mode for a method (IEC 62056-5-3, 5.3.7.2.2).
64#[derive(Debug, Clone, Copy, PartialEq, Eq)]
65pub enum MethodAccessMode {
66    /// No access to this method.
67    NoAccess = 0,
68    /// Access allowed.
69    Access = 1,
70    /// Authenticated access required.
71    AuthenticatedAccess = 2,
72}
73
74impl MethodAccessMode {
75    /// Parses an access mode from its numeric value.
76    pub fn from_u8(v: u8) -> Option<Self> {
77        match v {
78            0 => Some(Self::NoAccess),
79            1 => Some(Self::Access),
80            2 => Some(Self::AuthenticatedAccess),
81            _ => None,
82        }
83    }
84
85    /// Whether this mode allows access.
86    pub fn allows_access(&self) -> bool {
87        !matches!(self, Self::NoAccess)
88    }
89
90    /// Whether this mode requires authentication.
91    pub fn requires_auth(&self) -> bool {
92        matches!(self, Self::AuthenticatedAccess)
93    }
94}
95
96/// Access rights for a single attribute (IEC 62056-5-3, 5.3.7.2.2).
97#[derive(Debug, Clone)]
98pub struct AttributeAccessItem {
99    /// The attribute id (1-based).
100    pub attribute_id: i8,
101    /// The access mode for this attribute.
102    pub access_mode: AttributeAccessMode,
103    /// Optional access selectors (null-data or array of integer).
104    pub access_selectors: Option<Vec<i8>>,
105}
106
107/// Access rights for a single method (IEC 62056-5-3, 5.3.7.2.2).
108#[derive(Debug, Clone)]
109pub struct MethodAccessItem {
110    /// The method id (1-based).
111    pub method_id: i8,
112    /// The access mode for this method.
113    pub access_mode: MethodAccessMode,
114}
115
116/// Complete access rights for an object (IEC 62056-5-3, 5.3.7.2.2).
117#[derive(Debug, Clone)]
118pub struct AccessRights {
119    /// Access rights for each attribute.
120    pub attribute_access: Vec<AttributeAccessItem>,
121    /// Access rights for each method.
122    pub method_access: Vec<MethodAccessItem>,
123}
124
125/// An entry in the Association LN `object_list` (IEC 62056-5-3, 5.3.7.2.2).
126#[derive(Debug, Clone)]
127pub struct ObjectListEntry {
128    /// The class id of the object.
129    pub class_id: u16,
130    /// The class version.
131    pub version: u8,
132    /// The logical name (OBIS code) of the object.
133    pub logical_name: Vec<u8>, // OBIS as 6 bytes
134    /// The access rights for this object.
135    pub access_rights: AccessRights,
136}
137
138impl ObjectListEntry {
139    /// Checks whether a read is allowed for the given attribute.
140    pub fn can_read(&self, attribute_id: i8) -> bool {
141        self.access_rights
142            .attribute_access
143            .iter()
144            .any(|item| item.attribute_id == attribute_id && item.access_mode.allows_read())
145    }
146
147    /// Checks whether a write is allowed for the given attribute.
148    pub fn can_write(&self, attribute_id: i8) -> bool {
149        self.access_rights
150            .attribute_access
151            .iter()
152            .any(|item| item.attribute_id == attribute_id && item.access_mode.allows_write())
153    }
154
155    /// Checks whether a method call is allowed.
156    pub fn can_invoke(&self, method_id: i8) -> bool {
157        self.access_rights
158            .method_access
159            .iter()
160            .any(|item| item.method_id == method_id && item.access_mode.allows_access())
161    }
162
163    /// Checks whether authentication is required for reading.
164    pub fn auth_required_read(&self, attribute_id: i8) -> bool {
165        self.access_rights
166            .attribute_access
167            .iter()
168            .any(|item| item.attribute_id == attribute_id && item.access_mode.requires_auth())
169    }
170
171    /// Checks whether authentication is required for writing.
172    pub fn auth_required_write(&self, attribute_id: i8) -> bool {
173        self.access_rights
174            .attribute_access
175            .iter()
176            .any(|item| item.attribute_id == attribute_id && item.access_mode.requires_auth())
177    }
178}
179
180/// Builds an object_list entry with default read/write access for all attributes.
181// COSEM attribute/method indices are always <128 in practice (i8-valued on the wire).
182#[allow(clippy::cast_possible_wrap)]
183pub fn full_access_entry(class_id: u16, version: u8, obis: &[u8], attr_count: u8, method_count: u8) -> ObjectListEntry {
184    let attribute_access = (1..=attr_count)
185        .map(|id| AttributeAccessItem {
186            attribute_id: id as i8,
187            access_mode: AttributeAccessMode::ReadWrite,
188            access_selectors: None,
189        })
190        .collect();
191
192    let method_access = (1..=method_count)
193        .map(|id| MethodAccessItem { method_id: id as i8, access_mode: MethodAccessMode::Access })
194        .collect();
195
196    ObjectListEntry {
197        class_id,
198        version,
199        logical_name: obis.to_vec(),
200        access_rights: AccessRights { attribute_access, method_access },
201    }
202}
203
204/// Builds an object_list entry with read-only access for all attributes.
205// COSEM attribute/method indices are always <128 in practice (i8-valued on the wire).
206#[allow(clippy::cast_possible_wrap)]
207pub fn read_only_entry(class_id: u16, version: u8, obis: &[u8], attr_count: u8, method_count: u8) -> ObjectListEntry {
208    let attribute_access = (1..=attr_count)
209        .map(|id| AttributeAccessItem {
210            attribute_id: id as i8,
211            access_mode: AttributeAccessMode::ReadOnly,
212            access_selectors: None,
213        })
214        .collect();
215
216    let method_access = (1..=method_count)
217        .map(|id| MethodAccessItem { method_id: id as i8, access_mode: MethodAccessMode::NoAccess })
218        .collect();
219
220    ObjectListEntry {
221        class_id,
222        version,
223        logical_name: obis.to_vec(),
224        access_rights: AccessRights { attribute_access, method_access },
225    }
226}