//! The `geonetworking` library decodes and encodes GeoNetworking packets according to EN 302 636-4-1 v1.3.1
//!
//! # Feature Flags
//! Some features can be disabled to reduce dependencies when they are not needed:
//!
//! - `json` (enabled by default): Serialization to and from JSON (using `serde`)
//! - `validate` (enabled by default): Basic signature validation
//!
//! Since both features are enabled by default, use `default-features = false` in your `Cargo.toml`.
//!
//! # Decoding
//! The central data type of this crate is the GeoNetworking [`Packet`] which contains all headers and the payload.
//! It implements the [`Decode`] trait which provides the [decode](`Decode::decode`) method to decode a GeoNetworking packet from a binary buffer.
//! The output is a `Result`-wrapped [`Decoded`] struct, which contains the decoded data and the number of consumed bytes.
//!
//! ```rust
//! use geonetworking::*;
//!
//! // GeoNetworking Header with security and a payload of BTP-B and CAM
//! let data: &'static [u8] = &[
//! 0x12, 0x00, 0x05, 0x01, 0x03, 0x81, 0x00, 0x40, 0x03, 0x80, 0x5f, 0x20, 0x50, 0x02, 0x80, 0x00, 0x3b, 0x01, 0x00, 0x14, 0x00, 0x1e, 0x0d, 0xdf, 0x3f, 0x5b, 0x7d, 0xa0, 0xcd, 0xf2, 0x54, 0x1c, 0x81, 0x28, 0xaf, 0x07, 0xc5, 0xdd, 0xa5, 0x80, 0x04, 0x09, 0xf6, 0x00, 0x00, 0x00, 0x00, 0x07, 0xd1, 0x00, 0x00, 0x02, 0x02, 0xdf, 0x3f, 0x5b, 0x7d, 0xf2, 0x54, 0x40, 0x5a, 0x44, 0xc2, 0x35, 0xee, 0x61, 0xf5, 0xf4, 0xa2, 0x06, 0x20, 0x60, 0x00, 0x47, 0xbe, 0x50, 0x48, 0x9f, 0x7f, 0xa0, 0x02, 0x1c, 0xbf, 0xe9, 0xea, 0x83, 0x33, 0xff, 0x01, 0xff, 0xfa, 0x00, 0x28, 0x33, 0x00, 0x00, 0x1b, 0xfb, 0xc2, 0xff, 0x94, 0x36, 0x60, 0x7f, 0xff, 0x00, 0xc0, 0x01, 0x24, 0x00, 0x02, 0x34, 0xf4, 0x24, 0x7b, 0xf3, 0x0c, 0x02, 0x05, 0x80, 0x05, 0x01, 0x01, 0x7c, 0xe7, 0xf9, 0x81, 0x01, 0x01, 0x80, 0x03, 0x00, 0x80, 0x5d, 0x5d, 0xcb, 0xee, 0xfb, 0xe7, 0xd2, 0x2d, 0x30, 0x83, 0x00, 0x00, 0x00, 0x00, 0x00, 0x24, 0xbd, 0x2d, 0x05, 0x86, 0x00, 0x01, 0xe0, 0x01, 0x07, 0x80, 0x01, 0x24, 0x81, 0x04, 0x03, 0x01, 0xff, 0xfc, 0x80, 0x01, 0x25, 0x81, 0x05, 0x04, 0x01, 0xff, 0xff, 0xff, 0x80, 0x01, 0x8c, 0x81, 0x05, 0x04, 0x02, 0xff, 0xff, 0xe0, 0x00, 0x01, 0x8d, 0x80, 0x02, 0x02, 0x7e, 0x81, 0x02, 0x01, 0x01, 0x80, 0x02, 0x02, 0x7f, 0x81, 0x02, 0x01, 0x01, 0x00, 0x02, 0x03, 0xff, 0x80, 0x80, 0x82, 0xde, 0xa0, 0x8e, 0xa8, 0xe8, 0x3e, 0x46, 0x24, 0x4a, 0x8f, 0x98, 0xa1, 0xdf, 0x15, 0x1e, 0x93, 0x8d, 0x26, 0x39, 0xac, 0xda, 0xa4, 0x10, 0x80, 0x48, 0x80, 0xaa, 0x36, 0x2e, 0x85, 0x5d, 0xad, 0x81, 0x83, 0x5b, 0xd8, 0x00, 0xfc, 0xe3, 0x7f, 0x70, 0x70, 0xdf, 0xf5, 0x90, 0x27, 0xa3, 0x9d, 0x19, 0xae, 0x8d, 0xe9, 0x60, 0x76, 0x12, 0xcb, 0xb2, 0x30, 0x9a, 0xf5, 0xfe, 0x89, 0x43, 0x30, 0x08, 0x02, 0x8e, 0x29, 0x4f, 0xf7, 0xef, 0xae, 0xca, 0xbf, 0x82, 0x4c, 0xab, 0x93, 0x27, 0x04, 0xcb, 0x98, 0x20, 0x80, 0xf3, 0x42, 0x90, 0x0c, 0x1f, 0xda, 0x11, 0xf6, 0xda, 0x43, 0x40, 0x05, 0xed, 0x85, 0x80, 0x82, 0x36, 0x99, 0x42, 0xdc, 0x48, 0x8d, 0xe7, 0x2f, 0x81, 0xeb, 0x82, 0x3b, 0xf9, 0x3d, 0xbd, 0xa1, 0xad, 0xb6, 0x37, 0x4b, 0xcd, 0x3d, 0x41, 0x69, 0x07, 0x33, 0x50, 0xc2, 0x6b, 0x72, 0x8b, 0xbe, 0x37, 0x47, 0x18, 0x35, 0x4a, 0x6f, 0xf6, 0xc1, 0x93, 0x6b, 0x25, 0x59, 0x94, 0xb9, 0x13, 0x49, 0xd2, 0x47, 0x5f, 0x73, 0x61, 0x97, 0x8b, 0xd7, 0x93, 0x21, 0x57, 0x37, 0x53, 0xc1, 0x4d, 0x36,
//! ];
//! let result = Packet::decode(data).unwrap();
//! println!("Consumed {} bytes and decoded GeoNetworking packet {:?}", result.bytes_consumed, result.decoded);
//! ```
//!
//! # Encoding a GeoNetworking Header
//! The crate's [`Encode`] trait provides two (three with the `json` feature enabled) methods for encoding items:
//!
//! - [`Encode::encode`] takes an [`Encoder`] as input and can be used for concatenating multiple items in one encoding
//! - For encoding a single item [`Encode::encode_to_vec`] provides a shorthand that returns immediately the bytes of the encoding
//!
//! **Note**: Currently, only non-secured packets can be encoded
//!
//! ```rust
//! use geonetworking::*;
//!
//! let packet = Packet::Unsecured {
//! basic: en302636_4_1::BasicHeader::try_new(
//! 1,
//! en302636_4_1::NextAfterBasic::CommonHeader,
//! en302636_4_1::Lifetime(80),
//! 1,
//! ).expect("Failed to create BasicHeader"),
//! common: en302636_4_1::CommonHeader::new(
//! en302636_4_1::NextAfterCommon::BTPB,
//! en302636_4_1::HeaderType::TopologicallyScopedBroadcast(
//! en302636_4_1::BroadcastType::SingleHop,
//! ),
//! en302636_4_1::TrafficClass::try_new(false, false, 2).expect("Failed to create TrafficClass"),
//! [false; 8],
//! 1,
//! 1,
//! ),
//! extended: Some(en302636_4_1::ExtendedHeader::SHB(en302636_4_1::SingleHopBroadcast {
//! source_position_vector: en302636_4_1::LongPositionVector::try_new(
//! en302636_4_1::Address {
//! manually_configured: false,
//! station_type: en302636_4_1::StationType::Unknown,
//! reserved: arbitrary_int::u10::new(0x0106),
//! address: [0, 96, 224, 105, 87, 141],
//! },
//! en302636_4_1::Timestamp(542947520),
//! 535574568,
//! 99765648,
//! false,
//! 680,
//! 2122,
//! ).expect("Failed to create LongPositionVector"),
//! media_dependent_data: [127, 0, 184, 0],
//! })),
//! payload: &[42]
//! };
//!
//! // Encode using an encoder
//! let mut encoder = Encoder::new();
//! packet.encode(&mut encoder).unwrap();
//!
//! let output: Vec<u8> = encoder.into();
//!
//! // Encode and return bytes
//! let bytes = packet.encode_to_vec().unwrap();
//!
//! assert_eq!(output, bytes);
//! ```
//!
//! # Validating a Packet
//! **Note**: Packet validation is only available in the `validate` feature.
//!
//! The [`Validate`] trait exposes a [validate](`Validate::validate`) method that checks whether the implementing type is valid.
//!
//! ```rust
//! use geonetworking::*;
//!
//! // GeoNetworking Header with security and a payload of BTP-B and CAM
//! let data: &'static [u8] = &[
//! 0x12, 0x00, 0x05, 0x01, 0x03, 0x81, 0x00, 0x40, 0x03, 0x80, 0x81, 0xbd, 0x20, 0x50, 0x02, 0x80, 0x00, 0x99, 0x01, 0x00, 0x14, 0x00, 0xca, 0xb0, 0xa5, 0x28, 0x3d, 0x0a, 0x2c, 0xd5, 0x54, 0xcf, 0x1c, 0x7f, 0x37, 0xa3, 0x07, 0xc6, 0xb6, 0x44, 0x82, 0xcc, 0x0b, 0xbf, 0x00, 0x00, 0x00, 0x00, 0x07, 0xd1, 0x00, 0x00, 0x02, 0x02, 0xa5, 0x28, 0x3d, 0x0a, 0x54, 0xcf, 0x40, 0x5a, 0x44, 0x84, 0x14, 0x6e, 0x62, 0x11, 0x08, 0x80, 0xb8, 0x0b, 0x80, 0x00, 0x47, 0xa7, 0xce, 0x48, 0xbb, 0xf1, 0x01, 0x54, 0x08, 0x82, 0x98, 0x8a, 0x8f, 0x34, 0x12, 0x62, 0x01, 0x0a, 0x00, 0x28, 0x73, 0x00, 0x00, 0xcb, 0xff, 0x7d, 0x00, 0x54, 0x31, 0x92, 0x00, 0x09, 0xdf, 0xbf, 0xd8, 0x26, 0x75, 0x8f, 0x10, 0x07, 0x7f, 0x00, 0x1d, 0x40, 0x10, 0x4c, 0x69, 0x80, 0x95, 0xf7, 0xf5, 0xc6, 0x06, 0x5c, 0x64, 0x14, 0x06, 0x2b, 0xbf, 0x80, 0x70, 0x4b, 0x3b, 0x1e, 0xc0, 0x08, 0x1d, 0xfb, 0xf6, 0x82, 0x70, 0x98, 0xf1, 0x00, 0x31, 0xef, 0xe0, 0x1c, 0x13, 0x6c, 0xc7, 0x88, 0x01, 0x67, 0x7e, 0xfd, 0x60, 0x9e, 0x86, 0x3b, 0x00, 0x0b, 0x3b, 0xf8, 0xcb, 0x04, 0x7e, 0xb1, 0xc4, 0x00, 0x4f, 0xdf, 0xc5, 0xa8, 0x23, 0xdd, 0x8e, 0x20, 0x02, 0x7e, 0xfe, 0x2c, 0x41, 0x1c, 0xec, 0x67, 0x00, 0x13, 0xf7, 0xef, 0xa6, 0x09, 0xce, 0x63, 0x60, 0x00, 0xb3, 0x40, 0x01, 0x24, 0x00, 0x02, 0x3a, 0xff, 0x21, 0x55, 0xe9, 0x67, 0x81, 0x01, 0x01, 0x80, 0x03, 0x00, 0x80, 0x5d, 0x5d, 0xcb, 0xee, 0xfb, 0xe7, 0xd2, 0x2d, 0x30, 0x83, 0x00, 0x00, 0x00, 0x00, 0x00, 0x25, 0x47, 0x9a, 0x85, 0x86, 0x00, 0x01, 0xe0, 0x01, 0x07, 0x80, 0x01, 0x24, 0x81, 0x04, 0x03, 0x01, 0xff, 0xfc, 0x80, 0x01, 0x25, 0x81, 0x05, 0x04, 0x01, 0xff, 0xff, 0xff, 0x80, 0x01, 0x8c, 0x81, 0x05, 0x04, 0x02, 0xff, 0xff, 0xe0, 0x00, 0x01, 0x8d, 0x80, 0x02, 0x02, 0x7e, 0x81, 0x02, 0x01, 0x01, 0x80, 0x02, 0x02, 0x7f, 0x81, 0x02, 0x01, 0x01, 0x00, 0x02, 0x03, 0xff, 0x80, 0x80, 0x83, 0x84, 0x16, 0x11, 0x01, 0xf5, 0x8b, 0x0a, 0x44, 0x8d, 0xb0, 0x60, 0x45, 0x96, 0x21, 0xec, 0x8b, 0xaf, 0xf0, 0xb2, 0x35, 0xd3, 0x5d, 0xc5, 0xe0, 0xd9, 0x7b, 0x3e, 0xee, 0x12, 0xc1, 0x5e, 0xe7, 0x81, 0x80, 0x9c, 0x28, 0x35, 0xd1, 0xd5, 0x7e, 0x28, 0x92, 0xd9, 0xb8, 0x66, 0x75, 0xd8, 0x0a, 0x4b, 0x75, 0x7c, 0x55, 0x49, 0x8f, 0x58, 0x41, 0xf0, 0xc5, 0xca, 0xe7, 0x7a, 0x4d, 0xd4, 0xc3, 0x4a, 0x74, 0x7c, 0x0a, 0x34, 0xd8, 0x2b, 0x5f, 0x28, 0x35, 0xde, 0xc9, 0x9e, 0x39, 0x45, 0x59, 0xde, 0x3d, 0x5e, 0x40, 0x43, 0x0a, 0x5c, 0x7a, 0x7e, 0x6e, 0x26, 0x06, 0x36, 0x9b, 0x6a, 0x96, 0xb1, 0x2c, 0x80, 0x83, 0xf6, 0xd4, 0x0f, 0x37, 0x94, 0xf1, 0x02, 0xf3, 0x37, 0xe2, 0xa8, 0xb7, 0x2a, 0x82, 0xf9, 0xca, 0xe8, 0xf6, 0x7f, 0x9f, 0x32, 0xf4, 0xe4, 0x61, 0x22, 0x43, 0x95, 0x6a, 0xab, 0x81, 0x6b, 0x92, 0x71, 0x39, 0x11, 0xd7, 0xb6, 0xe2, 0x93, 0x6f, 0xc4, 0xef, 0x79, 0x2e, 0x41, 0x55, 0x02, 0x58, 0x0f, 0x4e, 0xf5, 0xca, 0x4c, 0x12, 0x6d, 0xd9, 0x76, 0x7f, 0xab, 0x9c, 0x87, 0xd7, 0x36, 0xa5,
//! ];
//! let packet = Packet::decode(data).unwrap().decoded;
//! #[cfg(feature = "validate")]
//! assert_eq!(packet.validate(), Ok(ValidationResult::Success));
//! ```
#![cfg_attr(all(not(test), not(feature = "validate")), no_std)]
extern crate alloc;
use alloc::string::ToString;
#[cfg(all(feature = "json", not(feature = "validate")))]
use alloc::vec;
#[cfg(feature = "validate")]
use std::fmt::Debug;
#[cfg(not(feature = "validate"))]
use {alloc::vec::Vec, core::fmt::Debug};
use arbitrary_int::{i15, u4};
mod decode;
mod encode;
mod standards;
pub(crate) mod util;
#[cfg(feature = "validate")]
mod validate;
pub use crate::standards::en302636_4_1;
pub use crate::standards::ieee1609dot2;
pub use decode::UnsecuredHeader;
pub use decode::{Decode, DecodeError, Decoded};
pub use encode::{Encode, EncodeError, Encoder};
#[cfg(feature = "validate")]
pub use validate::{Validate, ValidationError, ValidationResult};
#[cfg(feature = "json")]
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize))]
/// C-ITS GeoNetworking packet
///
/// A geonetworking packet always contains a `basic` and `common` header.
/// When message signing (secured packet) is used, a `secured` header is added after the basic header which signs all data following itself.
///
/// Usually a message will continue with an `extended` header.
/// The payload is directly present in `Unsecured` packets or needs to be retrieved using [`Self::secured_payload_after_gn`] in [`Self::Secured`]
pub enum Packet<'input> {
Unsecured {
basic: en302636_4_1::BasicHeader,
common: en302636_4_1::CommonHeader,
extended: Option<en302636_4_1::ExtendedHeader>,
#[cfg_attr(feature = "serde", serde(borrow))]
payload: &'input [u8],
},
Secured {
basic: en302636_4_1::BasicHeader,
secured: ieee1609dot2::Ieee1609Dot2Data<'input>,
common: en302636_4_1::CommonHeader,
extended: Option<en302636_4_1::ExtendedHeader>,
},
}
impl<'p> Packet<'p> {
/// Retrieves the slice of the secured IEEE 1609.2 data
/// that represents the payload after GeoNetworking Common and
/// Extended headers.
/// ### Example
/// Consider a CAM message with BTB-B and secured GeoNetworking Header
/// ```ignore
/// Ieee1609Dot2Data->content->signed_data->tbs_data->payload->data->content->unsecured_data
/// |---Common---|---Extended---|--BTP-B--|--------CAM---------|
/// ^ ^
/// |_________return slice_________|
/// ```
#[must_use]
pub fn secured_payload_after_gn(&self) -> Option<&'p [u8]> {
match self {
Packet::Secured {
secured, common, ..
} => match common.header_type_and_subtype {
en302636_4_1::HeaderType::Any => secured.data_payload().map(|p| &p[8..]),
en302636_4_1::HeaderType::Beacon => secured.data_payload().map(|p| &p[8 + 24..]),
en302636_4_1::HeaderType::GeoUnicast => {
secured.data_payload().map(|p| &p[8 + 36..])
}
en302636_4_1::HeaderType::GeoAnycast(_)
| en302636_4_1::HeaderType::GeoBroadcast(_) => {
secured.data_payload().map(|p| &p[8 + 44..])
}
en302636_4_1::HeaderType::TopologicallyScopedBroadcast(_) => {
secured.data_payload().map(|p| &p[8 + 28..])
}
en302636_4_1::HeaderType::LocationService(
en302636_4_1::LocationServiceType::Request,
) => secured.data_payload().map(|p| &p[8 + 36..]),
en302636_4_1::HeaderType::LocationService(
en302636_4_1::LocationServiceType::Reply,
) => secured.data_payload().map(|p| &p[8 + 48..]),
},
Packet::Unsecured { .. } => None,
}
}
/// Returns a reference to the Common header regardless of Packet type
#[must_use]
pub fn common(&self) -> &en302636_4_1::CommonHeader {
match self {
Packet::Unsecured { common, .. } | Packet::Secured { common, .. } => common,
}
}
/// Returns a reference to the Basic header regardless of Packet type
#[must_use]
pub fn basic(&self) -> &en302636_4_1::BasicHeader {
match self {
Packet::Unsecured {
common: _,
basic,
extended: _,
payload: _,
}
| Packet::Secured {
basic,
secured: _,
common: _,
extended: _,
} => basic,
}
}
/// Returns a reference to the Extended header regardless of Packet type
#[must_use]
pub fn extended(&self) -> &Option<en302636_4_1::ExtendedHeader> {
match self {
Packet::Unsecured {
common: _,
basic: _,
extended,
payload: _,
}
| Packet::Secured {
basic: _,
secured: _,
common: _,
extended,
} => extended,
}
}
/// Returns a reference to the payload of a signed or unsigned packet (or None if secured packet has not payload)
///
/// The payload buffer will contain a header (usually BTP) as specified in the `next_header` field of the common header.
#[must_use]
pub fn payload(&self) -> Option<&'p [u8]> {
match self {
Self::Unsecured { payload, .. } => Some(*payload),
s @ Self::Secured { .. } => s.secured_payload_after_gn(),
}
}
/// Extracts the BTP payload
///
/// # Errors
/// Returns a human-readable string if
/// - a secured packet has no payload
/// - or the next header is not a BTP header
pub fn btp_payload(&self) -> Result<&'p [u8], alloc::string::String> {
let Some(payload) = self.payload() else {
return Err("No data in secured packet".to_string());
};
match self.common().next_header {
en302636_4_1::NextAfterCommon::BTPA | en302636_4_1::NextAfterCommon::BTPB => {
let (_, payload) = payload.split_at(4);
Ok(payload)
}
_ => Err("Unsupported BTP header type".to_string()),
}
}
/// Determines if the packet was hopped
#[must_use]
pub fn is_hopped(&self) -> bool {
// A packet was hopped when the remaining hop limit is lower than the maximum hop limit.
// Directly received data has both parameters at the same value (SHB has both set to 1).
self.common().maximum_hop_limit > self.basic().remaining_hop_limit
}
/// Gets the source position vector from the extended header (if header is present)
#[must_use]
pub fn source_position_vector(&self) -> Option<en302636_4_1::LongPositionVector> {
self.extended().as_ref().map(|eh| {
match eh {
en302636_4_1::ExtendedHeader::Beacon(beacon) => &beacon.source_position_vector,
en302636_4_1::ExtendedHeader::GUC(geo_unicast) => {
&geo_unicast.source_position_vector
}
en302636_4_1::ExtendedHeader::TSB(topologically_scoped_broadcast) => {
&topologically_scoped_broadcast.source_position_vector
}
en302636_4_1::ExtendedHeader::SHB(single_hop_broadcast) => {
&single_hop_broadcast.source_position_vector
}
en302636_4_1::ExtendedHeader::GBC(geo_anycast)
| en302636_4_1::ExtendedHeader::GAC(geo_anycast) => {
&geo_anycast.source_position_vector
}
en302636_4_1::ExtendedHeader::LSRequest(lsrequest) => {
&lsrequest.source_position_vector
}
en302636_4_1::ExtendedHeader::LSReply(lsreply) => &lsreply.source_position_vector,
}
.clone()
})
}
}
#[cfg(test)]
mod tests {}