//! 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: BasicHeader {
//! version: 1,
//! next_header: NextAfterBasic::CommonHeader,
//! reserved: bits![0; 8],
//! lifetime: Lifetime(80),
//! remaining_hop_limit: 1,
//! },
//! common: CommonHeader {
//! next_header: NextAfterCommon::BTPB,
//! reserved_1: bits![0, 0, 0, 0],
//! header_type_and_subtype: HeaderType::TopologicallyScopedBroadcast(
//! BroadcastType::SingleHop,
//! ),
//! traffic_class: TrafficClass {
//! store_carry_forward: false,
//! channel_offload: false,
//! traffic_class_id: 2,
//! },
//! flags: bits![0, 0, 0, 0, 0, 0, 0, 0],
//! payload_length: 1,
//! maximum_hop_limit: 1,
//! reserved_2: bits![0, 0, 0, 0, 0, 0, 0, 0],
//! },
//! extended: Some(ExtendedHeader::SHB(SingleHopBroadcast {
//! source_position_vector: LongPositionVector {
//! gn_address: Address {
//! manually_configured: false,
//! station_type: StationType::Unknown,
//! reserved: bits![0, 1, 0, 0, 0, 0, 0, 1, 1, 0],
//! address: [0, 96, 224, 105, 87, 141],
//! },
//! timestamp: Timestamp(542947520),
//! latitude: 535574568,
//! longitude: 99765648,
//! position_accuracy: false,
//! speed: 680,
//! heading: 2122,
//! },
//! 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 bitvec::prelude::*;
use bytes::Bytes;
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::{de::Visitor, Deserialize, Serialize};
#[cfg(feature = "json")]
struct BitsVisitor<const SIZE: usize>;
#[cfg(feature = "json")]
impl<'de, const SIZE: usize> Visitor<'de> for BitsVisitor<SIZE> {
type Value = Bits<SIZE>;
fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
formatter.write_str("a sequence of boolean values")
}
fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
where
A: serde::de::SeqAccess<'de>,
{
let mut bits = vec![];
while let Some(bit) = seq.next_element::<bool>()? {
bits.push(bit);
}
Ok(Bits(bits.iter().collect::<BitVec<u8, Msb0>>()))
}
}
#[derive(Clone, PartialEq)]
pub struct Bits<const SIZE: usize>(pub BitVec<u8, Msb0>);
impl<const SIZE: usize> Debug for Bits<SIZE> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
self.0.fmt(f)
}
}
#[cfg(feature = "json")]
impl<'de, const SIZE: usize> Deserialize<'de> for Bits<SIZE> {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
deserializer.deserialize_seq(BitsVisitor::<SIZE>)
}
}
#[cfg(feature = "json")]
impl<const SIZE: usize> Serialize for Bits<SIZE> {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer,
{
serializer.collect_seq(self.0.iter().map(|bit| *bit))
}
}
#[macro_export]
/// Shorthand to define a bit-vector "literal"
///
/// This macro accepts:
///
/// - a comma-separated list of 1s and 0s, like `bits![0, 0, 0, 0]`
/// - a value (1 or 0) and a length value (usize) separated by a semicolon, like `geonetworking::bits![0; 8]`
///
macro_rules! bits {
($val:expr; $len:expr) => {
Bits(bitvec::vec::BitVec::<u8, bitvec::prelude::Msb0>::repeat($val != 0, $len))
};
($($val:expr),* $(,)?) => {
Bits(bitvec::prelude::bits![u8, bitvec::prelude::Msb0; $($val),*].to_bitvec())
};
}
#[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: BasicHeader,
common: CommonHeader,
extended: Option<ExtendedHeader>,
#[cfg_attr(feature = "serde", serde(borrow))]
payload: &'input [u8],
},
Secured {
basic: BasicHeader,
secured: Ieee1609Dot2Data<'input>,
common: CommonHeader,
extended: Option<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 {
HeaderType::Any => secured.data_payload().map(|p| &p[8..]),
HeaderType::Beacon => secured.data_payload().map(|p| &p[8 + 24..]),
HeaderType::GeoUnicast => secured.data_payload().map(|p| &p[8 + 36..]),
HeaderType::GeoAnycast(_) | HeaderType::GeoBroadcast(_) => {
secured.data_payload().map(|p| &p[8 + 44..])
}
HeaderType::TopologicallyScopedBroadcast(_) => {
secured.data_payload().map(|p| &p[8 + 28..])
}
HeaderType::LocationService(LocationServiceType::Request) => {
secured.data_payload().map(|p| &p[8 + 36..])
}
HeaderType::LocationService(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) -> &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) -> &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<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 {
NextAfterCommon::BTPA | 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<LongPositionVector> {
self.extended().as_ref().map(|eh| {
match eh {
ExtendedHeader::Beacon(beacon) => &beacon.source_position_vector,
ExtendedHeader::GUC(geo_unicast) => &geo_unicast.source_position_vector,
ExtendedHeader::TSB(topologically_scoped_broadcast) => {
&topologically_scoped_broadcast.source_position_vector
}
ExtendedHeader::SHB(single_hop_broadcast) => {
&single_hop_broadcast.source_position_vector
}
ExtendedHeader::GBC(geo_anycast) | ExtendedHeader::GAC(geo_anycast) => {
&geo_anycast.source_position_vector
}
ExtendedHeader::LSRequest(lsrequest) => &lsrequest.source_position_vector,
ExtendedHeader::LSReply(lsreply) => &lsreply.source_position_vector,
}
.clone()
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn gets_lifetime_base() {
assert_eq!(Lifetime(127).base(), 3);
assert_eq!(Lifetime(126).base(), 2);
assert_eq!(Lifetime(125).base(), 1);
}
#[test]
fn gets_lifetime_multiplier() {
assert_eq!(Lifetime(5).multiplier(), 1);
assert_eq!(Lifetime(9).multiplier(), 2);
assert_eq!(Lifetime(125).multiplier(), 31);
assert_eq!(Lifetime(255).multiplier(), 63);
}
}