oxirush-utils

What the OxiRush crates share, in Rust: the identities of 3GPP networks as values, and one JSON tree with paths for the messages of every protocol, in no_std and with no dependency unless a feature asks for one.

use oxirush_utils::identity::{Guti5g, Plmn};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let plmn: Plmn = "310-410".parse()?;
    let guti = Guti5g::new(plmn, 0xca, 0x3fe, 0x01, 0xdead_beef)?;

    // The three octets of a PLMN in a NAS message, and in an NGAP or S1AP message
    println!("{plmn}: {:02x?} in NAS, {:02x?} in NGAP", plmn.to_nas_octets(), plmn.to_ap_octets());

    // A 5G-GUTI as text, and as a 5GS mobile identity
    println!("{guti}: {:02x?}", guti.to_nas_octets());
    Ok(())
}

310-410: [13, 00, 14] in NAS, [13, 40, 01] in NGAP
5g-guti-310410caff81deadbeef: [f2, 13, 00, 14, ca, ff, 81, de, ad, be, ef]

Each example is followed by its output.

Installation

[dependencies]
oxirush-utils = { version = "0.1", features = ["alloc"] }
# With the tree and its paths, which need an allocator too:
# oxirush-utils = { version = "0.1", features = ["tree"] }
# Without an allocator, the values that have their digits in place:
# oxirush-utils = "0.1"

No feature is on by default. tree turns on the float_roundtrip feature of serde_json, so a number with a fraction is read as the nearest f64. A tree keeps the members of an object in the order the program wrote them.

The minimum supported Rust version is 1.88.

An identity through its forms

A value of identity is checked when it is made, and prints whole, in the text of the service based interfaces. An MNC has two or three digits, and how many is part of the value: 208-93 is not 208-093.

use oxirush_utils::identity::{Guti5g, Imsi, ImsiSuci, Plmn, RoutingIndicator, Supi};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // An IMSI whose MNC has three digits: its PLMN and its MSIN
    let imsi = Imsi::new("310410123456789")?;
    let (plmn, msin) = (imsi.plmn(3)?, imsi.msin(3)?);
    println!("IMSI {imsi}: PLMN {plmn}, MSIN {msin}");

    // Its SUCI under the null scheme, as text and as a 5GS mobile identity,
    // and the SUPI that the SUCI gives
    let suci = ImsiSuci::null(plmn, RoutingIndicator::default(), msin)?;
    println!("{suci}: {:02x?}", suci.to_nas_octets());
    println!("{}", Supi::from(suci.imsi().ok_or("a concealed MSIN")?));

    // The 5G-GUTI that an AMF assigns: AMF region, set and pointer, and the
    // 5G-TMSI. It is read back from its octets, and has a 5G-S-TMSI
    let guti = Guti5g::new(plmn, 0xca, 0x3fe, 0x01, 0xdead_beef)?;
    println!("{}", Guti5g::from_nas_octets(&guti.to_nas_octets())?.s_tmsi());

    // A PLMN that is not one says which member is wrong, and why
    println!("{}", Plmn::new("208", "9").unwrap_err());
    Ok(())
}

IMSI 310410123456789: PLMN 310-410, MSIN 123456789
suci-0-310-410-0-0-0-123456789: [01, 13, 00, 14, f0, ff, 00, 00, 21, 43, 65, 87, f9]
imsi-310410123456789
5g-s-tmsi-ff81deadbeef
`mnc` has 1 digit, and must have 2 or 3

Where each form goes

The NAS octets of an identity are the value of an IE of oxirush-nas. The AP octets of a PLMN are those of the identities of oxirush-ngap and oxirush-s1ap. The messages of all three are trees of this crate, read by the same paths.

use oxirush_nas::nas_5gs::{
    Nas5gsMessage, NasFGsMobileIdentity, NasFGsRegistrationResult, NasRegistrationAccept,
    RegistrationResult,
};
use oxirush_ngap::{helpers, ngap::PLMNIdentity};
use oxirush_utils::identity::{Guti5g, Plmn};
use oxirush_utils::tree;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let plmn: Plmn = "310-410".parse()?;
    let guti = Guti5g::new(plmn, 0xca, 0x3fe, 0x01, 0xdead_beef)?;

    // The 5G-GUTI of a REGISTRATION ACCEPT of oxirush-nas is this value
    let result = NasFGsRegistrationResult::from_result(RegistrationResult::ThreeGppAccess);
    let identity = NasFGsMobileIdentity::from_guti(guti);
    let accept = NasRegistrationAccept::new(result).with_fg_guti(identity);
    let accept = Nas5gsMessage::new_5gmm(accept);
    println!("{}", hex::encode(accept.encode()?));

    // The PLMN identity of a GUAMI of oxirush-ngap has its AP octets
    let guami = helpers::guami(PLMNIdentity(plmn.to_ap_octets()), 0xca, 0x3fe, 0x01)?;
    println!("{:?}: {:02x?}", guami.plmn_identity, guami.plmn_identity.0);

    // The tree of the NAS message is a tree of this crate
    let tree = accept.to_tree();
    println!("{:?}", tree::select(&tree, "/5g-guti/guti/tmsi")?);
    Ok(())
}

7e0042010177000bf2130014caff81deadbeef
PLMNIdentity(310-410): [13, 40, 01]
[Number(3735928559)]

IMEI, IMEISV, and the identities of EPS

use oxirush_utils::identity::{GutiEps, Imei, Imeisv, Imsi, Plmn, Tai5gs, TaiEps};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The identity digits of an IMSI in a mobile identity, after its type of identity
    let imsi = Imsi::new("208930000000001")?;
    println!("{:02x?}", imsi.to_nas_octets(1)?);

    // An IMEI as a mobile sends it, and with its check digit; the SVN of an IMEISV
    println!("{}", Imei::with_spare_digit("49015420323751")?);
    println!("{}", Imei::with_check_digit("49015420323751")?);
    println!("{}", Imeisv::new("4901542032375101")?.svn());

    // The GUTI of EPS: its MME group, MME code and M-TMSI; a tracking area of each system
    let plmn = Plmn::new("208", "93")?;
    println!("{}", GutiEps::new(plmn, 0x0002, 0x01, 0xc000_04f4));
    println!("{} {}", Tai5gs::new(plmn, 1)?, TaiEps::new(plmn, 1));
    Ok(())
}

[29, 80, 39, 00, 00, 00, 00, 10]
490154203237510
490154203237518
01
4g-guti-20893000201c00004f4
208-93-000001 208-93-0001

The SUCI in the form of a NAI

A SUPI that is not an IMSI is a NAI, and so is its SUCI. A NAI follows the grammar of RFC 7542; with the idna feature, its realm must also be a name that IDNA takes as written.

use oxirush_utils::identity::{NaiSuci, nai};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The example of TS 23.003 clause 28.7.3: a network specific identifier in clear
    let suci: NaiSuci = "type1.rid678.schid0.useriduser17@example.com".parse()?;
    println!("{:?} {:?} {}", suci.supi_type(), suci.clear(), suci.realm());

    // In a 5GS mobile identity, after the SUPI format of a network specific identifier
    println!("{:#04x}", suci.to_nas_octets()?[0]);

    // A realm has two labels at least
    println!("{}", nai::check_realm("example").unwrap_err());
    Ok(())
}

NetworkSpecific Some("user17") example.com
0x11
`realm` is written as a domain name of two labels at least, of letters, digits and hyphens, with no hyphen at either end and 63 octets at most each, as example.com

What other implementations send

from_nas_octets takes only the octets that the clause writes. The readers named _tolerant also take what other implementations are known to send, and say what departs from the clause. The documentation lists each tolerance with its clause and its evidence.

use oxirush_utils::identity::Imeisv;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // PacketRusher sends an IMEISV with 0000 where its end mark 1111 belongs
    let sent = [0x15, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
    println!("{}", Imeisv::from_nas_octets(5, &sent).unwrap_err());

    let (imeisv, faults) = Imeisv::from_nas_octets_tolerant(5, &sent)?;
    println!("{imeisv}, read with: {}", faults[0]);
    Ok(())
}

`imeisv` has the half octet 0x0 where its end mark is, and the end mark is 0xf
1110000000000000, read with: `imeisv` has the half octet 0x0 where its end mark is, and the end mark is 0xf

A type as a tree

With the tree feature, a message is a tree::Value: a JSON value in one form for every protocol, with octets in lower-case hexadecimal, numbers as JSON numbers, names read however they are written, and members in the order of the specification. tree! writes one as serde_json::json! does, and keeps that order.

use oxirush_utils::{tree, tree::{Members, Reading, Refused, Tree, Value}};

#[derive(Debug)]
struct Slice {
    sst: u8,
    sd: Option<[u8; 3]>,
}

impl Tree for Slice {
    const NAME: &'static str = "S-NSSAI";

    fn to_tree(&self) -> Value {
        let mut members = Members::new();
        members.put("sst", tree::unsigned(self.sst.into()));
        members.put_optional("sd", self.sd.map(|sd| tree::octets(&sd)));
        members.finish()
    }

    fn from_tree(value: &Value, reading: &mut Reading) -> Result<Self, Refused> {
        let members = reading.members(value, &["sst", "sd"])?;
        Ok(Self {
            sst: reading.member(&members, 0, |value, reading| reading.unsigned(value, 0, 255))? as u8,
            sd: reading.optional(&members, 1, |value, reading| reading.octet_array(value))?,
        })
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("{}", tree::to_value(&Slice { sst: 1, sd: Some([0, 0, 0xff]) }));

    // A name is read however it is written, and octets in either case
    let read: Slice = tree::from_value(&tree!({"SST": 2, "sd": "0000FF"}))?;
    println!("{read:?}");

    // A refusal says where and why
    println!("{}", tree::from_value::<Slice>(&tree!({"sst": 256})).unwrap_err());
    Ok(())
}

{"sst":1,"sd":"0000ff"}
Slice { sst: 2, sd: Some([0, 0, 255]) }
this is not a value of S-NSSAI: a number from 0 to 255 is expected, and 256 is written, at sst

Paths

A path is a JSON pointer: the name of a member, the position of an entry, * for each of them, and - for the end of a list in an insertion.

use oxirush_utils::tree;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut message = tree!({
        "message-type": "registration-request",
        "requested-nssai": [{"sst": 1}, {"sst": 2, "sd": "0000ff"}],
        "t3512-value": null,
    });

    // Select, by names however they are written; what is not there selects nothing
    println!("{:?}", tree::select(&message, "/Requested NSSAI/*/sst")?);
    println!("{:?}", tree::select(&message, "/t3512-value/unit")?);

    // A name that the value does not have is an error
    println!("{}", tree::select(&message, "/requested-nssai/0/sts").unwrap_err());

    // Each value with the path that selects it
    for (path, value) in tree::paths(&message) {
        println!("{path} = {value}");
    }

    // An edit is done whole, or not at all
    tree::set(&mut message, "/requested-nssai/0/sd", tree!("000001"))?;
    tree::insert(&mut message, "/requested-nssai/-", tree!({"sst": 3}))?;
    tree::remove(&mut message, "/requested-nssai/1")?;
    println!("{}", message["requested-nssai"]);
    Ok(())
}

[Number(1), Number(2)]
[]
"sts" is not a member of this value, which has sst, at /requested-nssai/0/sts
/message-type = "registration-request"
/requested-nssai/0/sst = 1
/requested-nssai/1/sst = 2
/requested-nssai/1/sd = "0000ff"
[{"sst":1,"sd":"000001"},{"sst":3}]

Any format of serde

With the serde feature, a type is serialized and deserialized through its tree, so YAML and JSON carry the same form.

use oxirush_utils::tree::{self, Members, Reading, Refused, Tree, Value};

#[derive(Debug, PartialEq)]
struct Timer {
    seconds: u32,
}

impl Tree for Timer {
    const NAME: &'static str = "GPRS timer";

    fn to_tree(&self) -> Value {
        let mut members = Members::new();
        members.put("seconds", tree::unsigned(self.seconds.into()));
        members.finish()
    }

    fn from_tree(value: &Value, reading: &mut Reading) -> Result<Self, Refused> {
        let members = reading.members(value, &["seconds"])?;
        let seconds = reading.member(&members, 0, |value, reading| reading.unsigned(value, 0, 11160))?;
        Ok(Self { seconds: seconds as u32 })
    }
}

// `Serialize` and `Deserialize`, through the tree
oxirush_utils::impl_serde!(Timer);

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let timer = Timer { seconds: 3600 };
    println!("{}", serde_json::to_string(&timer)?);
    print!("{}", serde_norway::to_string(&timer)?);
    println!("{:?}", serde_norway::from_str::<Timer>("Seconds: 3600")?);
    Ok(())
}

{"seconds":3600}
seconds: 3600
Timer { seconds: 3600 }

Limits

• It knows no codec and no message: the crates of each protocol do.
• It conceals no SUCI and derives no key: oxirush-security does.
• Supi checks that a NAI has a realm, and its length, but not its grammar: nai::check_realm and nai::check_username check that.
• A value of identity holds what the clauses allow. Octets that are no such identity stay octets in the crate that reads them.
• It has no JSON parser of its own: serde_json's reads a tree.

Performance

The tree of the crate against a serde_json::Value of the default features, on the same JSON, at 8865ad4 on core 2 of an AMD Ryzen 7 5700G (Linux 7.0, Rust 1.98.1), on 2026-10-18. A ratio is the time of serde_json over this crate's, and "about the same" is within 10 %:

A tree keeps the members of an object in their order, where a serde_json::Value sorts them. Reading a PLMN, an IMSI or a 5G-GUTI takes 9 to 14 ns without an allocation, and the SUCI of an IMSI 80 ns. benches/ has the allocations, the other identities and the method. In benches/:

cargo bench --bench tree

Tests and fuzzing

The identities are tested against their clauses, against what Open5GS, free5GC and PacketRusher sent in lab runs, and against themselves: every value is read back from the octets it writes, and any octets are either a value that writes them back or no value. The tests of oxirush-nas and oxirush-ngap on paths run here too, on trees written out without a codec, and so do trees of 65,536 entries, within a time bound. fuzz/ has two cargo-fuzz targets: identity reads octets and text as each identity, and paths takes any path and any edit on any tree.

cargo test --all-features
cargo +nightly fuzz run identity -- -max_total_time=60 -max_len=64
cargo +nightly fuzz run paths -- -max_total_time=60 -max_len=512

Each Rust block of this page is checked with what it prints (tests/readme.rs says how). The block that uses other crates of the family runs in the package of family/, which takes those crates at the revisions that its manifest names.

A pull request comes with a test for what it changes. Sign off your commits (git commit -s): by contributing you agree to the Developer Certificate of Origin. SECURITY.md says how to report a vulnerability.

The OxiRush family

• oxirush-utils: the 3GPP identities, and the JSON tree with its paths that the others share.
• oxirush-aper: aligned PER, the runtime of the NGAP and S1AP codecs.
• oxirush-nas: the NAS messages of 5GS and EPS.
• oxirush-security: NAS security, AKA and the derivation of keys.
• oxirush-ngap: NGAP, between a gNB and an AMF.
• oxirush-s1ap: S1AP, between an eNB and an MME.
• oxirush-gtp-u: GTP-U tunnels, with a test UPF.
• oxirush-sctp: SCTP sockets, which carry NGAP and S1AP.

License

Copyright 2025-2026 Valentin D'Emmanuele. Licensed under the Apache License, Version 2.0: see LICENSE.