Skip to main content

spodes_rs/service/
initiate.rs

1//! The xDLMS InitiateRequest / InitiateResponse APDUs (IEC 62056-5-3, 11.2).
2//!
3//! These A-XDR SEQUENCEs are carried opaquely in the `user-information` field of
4//! the ACSE AARQ / AARE APDUs (see [`super::acse`]). This module gives them a
5//! structured form so callers can negotiate the DLMS version, conformance block
6//! and PDU size without hand-assembling bytes.
7//!
8//! Reference (DLMS Green Book 11.2, LN referencing, no ciphering):
9//!
10//! ```text
11//! request:  01 00 00 00 06 5F1F 04 00 00 7E 1F 04B0
12//! response: 08    00 06 5F1F 04 00 00 7E 1F 01F4 0007
13//! ```
14//!
15//! `conformance` is the 24-bit block of the `[APPLICATION 30]` BIT STRING; it is
16//! kept here as the low 24 bits of a `u32`.
17
18use super::ServiceError;
19
20/// InitiateRequest APDU tag.
21pub const INITIATE_REQUEST_TAG: u8 = 0x01;
22/// InitiateResponse APDU tag.
23pub const INITIATE_RESPONSE_TAG: u8 = 0x08;
24
25/// The `[APPLICATION 30]` conformance BIT STRING identifier (two octets).
26const CONFORMANCE_TAG: [u8; 2] = [0x5F, 0x1F];
27
28/// An xDLMS InitiateRequest APDU.
29#[derive(Debug, Clone, PartialEq, Eq)]
30pub struct InitiateRequest {
31    /// Optional dedicated key (present only with ciphering).
32    pub dedicated_key: Option<Vec<u8>>,
33    /// `response-allowed` (BOOLEAN, default TRUE).
34    pub response_allowed: bool,
35    /// Optional proposed quality-of-service (not used in DLMS/COSEM).
36    pub proposed_quality_of_service: Option<i8>,
37    /// Proposed DLMS version number (6 for the current profile).
38    pub proposed_dlms_version: u8,
39    /// Proposed conformance block (low 24 bits).
40    pub proposed_conformance: u32,
41    /// Client-max-receive-pdu-size.
42    pub client_max_receive_pdu_size: u16,
43}
44
45impl InitiateRequest {
46    /// Encodes the APDU.
47    pub fn encode(&self) -> Vec<u8> {
48        let mut buf = vec![INITIATE_REQUEST_TAG];
49        match &self.dedicated_key {
50            None => buf.push(0x00),
51            Some(key) => {
52                buf.push(0x01);
53                // Dedicated keys are AES key material (<=32 bytes in practice).
54                #[allow(clippy::cast_possible_truncation)]
55                let len = key.len() as u8;
56                buf.push(len);
57                buf.extend_from_slice(key);
58            }
59        }
60        // response-allowed: usage flag then, if present, the boolean value.
61        if self.response_allowed {
62            buf.push(0x00); // default TRUE → omit value
63        } else {
64            buf.push(0x01);
65            buf.push(0x00); // FALSE
66        }
67        match self.proposed_quality_of_service {
68            None => buf.push(0x00),
69            Some(q) => {
70                buf.push(0x01);
71                // Raw octet round-tripped bit-for-bit via `as i8` on decode.
72                #[allow(clippy::cast_sign_loss)]
73                buf.push(q as u8);
74            }
75        }
76        buf.push(self.proposed_dlms_version);
77        push_conformance(self.proposed_conformance, &mut buf);
78        buf.extend_from_slice(&self.client_max_receive_pdu_size.to_be_bytes());
79        buf
80    }
81
82    /// Decodes the APDU.
83    pub fn decode(bytes: &[u8]) -> Result<InitiateRequest, ServiceError> {
84        if bytes.first() != Some(&INITIATE_REQUEST_TAG) {
85            return Err(ServiceError::UnexpectedTag(*bytes.first().unwrap_or(&0)));
86        }
87        let mut pos = 1;
88        let dedicated_key = match bytes.get(pos) {
89            Some(0x00) => {
90                pos += 1;
91                None
92            }
93            Some(0x01) => {
94                let len = *bytes.get(pos + 1).ok_or(ServiceError::Truncated)? as usize;
95                let start = pos + 2;
96                let key = bytes.get(start..start + len).ok_or(ServiceError::Truncated)?.to_vec();
97                pos = start + len;
98                Some(key)
99            }
100            Some(&other) => return Err(ServiceError::UnexpectedType(other)),
101            None => return Err(ServiceError::Truncated),
102        };
103        let response_allowed = match bytes.get(pos) {
104            Some(0x00) => {
105                pos += 1;
106                true
107            }
108            Some(0x01) => {
109                let value = *bytes.get(pos + 1).ok_or(ServiceError::Truncated)? != 0;
110                pos += 2;
111                value
112            }
113            Some(&other) => return Err(ServiceError::UnexpectedType(other)),
114            None => return Err(ServiceError::Truncated),
115        };
116        let proposed_quality_of_service = match bytes.get(pos) {
117            Some(0x00) => {
118                pos += 1;
119                None
120            }
121            Some(0x01) => {
122                // Raw octet round-tripped bit-for-bit from `q as u8` on encode.
123                #[allow(clippy::cast_possible_wrap)]
124                let q = *bytes.get(pos + 1).ok_or(ServiceError::Truncated)? as i8;
125                pos += 2;
126                Some(q)
127            }
128            Some(&other) => return Err(ServiceError::UnexpectedType(other)),
129            None => return Err(ServiceError::Truncated),
130        };
131        let proposed_dlms_version = *bytes.get(pos).ok_or(ServiceError::Truncated)?;
132        pos += 1;
133        let (proposed_conformance, n) = take_conformance(&bytes[pos..])?;
134        pos += n;
135        let b = bytes.get(pos..pos + 2).ok_or(ServiceError::Truncated)?;
136        let client_max_receive_pdu_size = u16::from_be_bytes([b[0], b[1]]);
137        Ok(InitiateRequest {
138            dedicated_key,
139            response_allowed,
140            proposed_quality_of_service,
141            proposed_dlms_version,
142            proposed_conformance,
143            client_max_receive_pdu_size,
144        })
145    }
146}
147
148/// An xDLMS InitiateResponse APDU.
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct InitiateResponse {
151    /// Optional negotiated quality-of-service (not used in DLMS/COSEM).
152    pub negotiated_quality_of_service: Option<i8>,
153    /// Negotiated DLMS version number.
154    pub negotiated_dlms_version: u8,
155    /// Negotiated conformance block (low 24 bits).
156    pub negotiated_conformance: u32,
157    /// Server-max-receive-pdu-size.
158    pub server_max_receive_pdu_size: u16,
159    /// VAA-name (0x0007 for LN referencing).
160    pub vaa_name: u16,
161}
162
163impl InitiateResponse {
164    /// Encodes the APDU.
165    pub fn encode(&self) -> Vec<u8> {
166        let mut buf = vec![INITIATE_RESPONSE_TAG];
167        match self.negotiated_quality_of_service {
168            None => buf.push(0x00),
169            Some(q) => {
170                buf.push(0x01);
171                // Raw octet round-tripped bit-for-bit via `as i8` on decode.
172                #[allow(clippy::cast_sign_loss)]
173                buf.push(q as u8);
174            }
175        }
176        buf.push(self.negotiated_dlms_version);
177        push_conformance(self.negotiated_conformance, &mut buf);
178        buf.extend_from_slice(&self.server_max_receive_pdu_size.to_be_bytes());
179        buf.extend_from_slice(&self.vaa_name.to_be_bytes());
180        buf
181    }
182
183    /// Decodes the APDU.
184    pub fn decode(bytes: &[u8]) -> Result<InitiateResponse, ServiceError> {
185        if bytes.first() != Some(&INITIATE_RESPONSE_TAG) {
186            return Err(ServiceError::UnexpectedTag(*bytes.first().unwrap_or(&0)));
187        }
188        let mut pos = 1;
189        let negotiated_quality_of_service = match bytes.get(pos) {
190            Some(0x00) => {
191                pos += 1;
192                None
193            }
194            Some(0x01) => {
195                // Raw octet round-tripped bit-for-bit from `q as u8` on encode.
196                #[allow(clippy::cast_possible_wrap)]
197                let q = *bytes.get(pos + 1).ok_or(ServiceError::Truncated)? as i8;
198                pos += 2;
199                Some(q)
200            }
201            Some(&other) => return Err(ServiceError::UnexpectedType(other)),
202            None => return Err(ServiceError::Truncated),
203        };
204        let negotiated_dlms_version = *bytes.get(pos).ok_or(ServiceError::Truncated)?;
205        pos += 1;
206        let (negotiated_conformance, n) = take_conformance(&bytes[pos..])?;
207        pos += n;
208        let b = bytes.get(pos..pos + 2).ok_or(ServiceError::Truncated)?;
209        let server_max_receive_pdu_size = u16::from_be_bytes([b[0], b[1]]);
210        pos += 2;
211        let v = bytes.get(pos..pos + 2).ok_or(ServiceError::Truncated)?;
212        let vaa_name = u16::from_be_bytes([v[0], v[1]]);
213        Ok(InitiateResponse {
214            negotiated_quality_of_service,
215            negotiated_dlms_version,
216            negotiated_conformance,
217            server_max_receive_pdu_size,
218            vaa_name,
219        })
220    }
221}
222
223/// Encodes the conformance block: `5F 1F 04 <unused=00> <3 octets>`.
224fn push_conformance(conformance: u32, buf: &mut Vec<u8>) {
225    buf.extend_from_slice(&CONFORMANCE_TAG);
226    buf.push(0x04); // length: unused-bits octet + 3 conformance octets
227    buf.push(0x00); // number of unused bits
228    let b = conformance.to_be_bytes();
229    buf.extend_from_slice(&b[1..]); // low 24 bits
230}
231
232/// Decodes a conformance block, returning its 24-bit value and octets consumed.
233fn take_conformance(bytes: &[u8]) -> Result<(u32, usize), ServiceError> {
234    if bytes.get(..2) != Some(&CONFORMANCE_TAG[..]) {
235        return Err(ServiceError::InvalidData);
236    }
237    let len = *bytes.get(2).ok_or(ServiceError::Truncated)? as usize;
238    // The value is <unused-bits> followed by the conformance octets.
239    let value = bytes.get(3..3 + len).ok_or(ServiceError::Truncated)?;
240    let mut conformance = 0u32;
241    for &b in &value[1..] {
242        conformance = (conformance << 8) | u32::from(b);
243    }
244    Ok((conformance, 3 + len))
245}
246
247#[cfg(test)]
248mod tests {
249    use super::*;
250
251    #[test]
252    fn initiate_request_matches_green_book_bytes() {
253        // DLMS Green Book 11.2, LN referencing, no ciphering.
254        let req = InitiateRequest {
255            dedicated_key: None,
256            response_allowed: true,
257            proposed_quality_of_service: None,
258            proposed_dlms_version: 6,
259            proposed_conformance: 0x007E1F,
260            client_max_receive_pdu_size: 0x04B0,
261        };
262        let bytes = req.encode();
263        assert_eq!(bytes, vec![0x01, 0x00, 0x00, 0x00, 0x06, 0x5F, 0x1F, 0x04, 0x00, 0x00, 0x7E, 0x1F, 0x04, 0xB0]);
264        assert_eq!(InitiateRequest::decode(&bytes).unwrap(), req);
265    }
266
267    #[test]
268    fn initiate_response_matches_green_book_bytes() {
269        let resp = InitiateResponse {
270            negotiated_quality_of_service: None,
271            negotiated_dlms_version: 6,
272            negotiated_conformance: 0x007E1F,
273            server_max_receive_pdu_size: 0x01F4,
274            vaa_name: 0x0007,
275        };
276        let bytes = resp.encode();
277        assert_eq!(bytes, vec![0x08, 0x00, 0x06, 0x5F, 0x1F, 0x04, 0x00, 0x00, 0x7E, 0x1F, 0x01, 0xF4, 0x00, 0x07]);
278        assert_eq!(InitiateResponse::decode(&bytes).unwrap(), resp);
279    }
280
281    #[test]
282    fn initiate_request_with_dedicated_key_and_no_response_round_trips() {
283        let req = InitiateRequest {
284            dedicated_key: Some(vec![0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]),
285            response_allowed: false,
286            proposed_quality_of_service: Some(4),
287            proposed_dlms_version: 6,
288            proposed_conformance: 0x101D,
289            client_max_receive_pdu_size: 0x0200,
290        };
291        assert_eq!(InitiateRequest::decode(&req.encode()).unwrap(), req);
292    }
293}