Crate nsap_address

Expand description

§X.213 NSAP Library

ITU-T Recommendation X.213 Network Service Access Point (NSAP) address parsing and printing. These address types were designed for use in OSI networking, but have full compatibility with IP networking. Since OSI networking is ancient history, this library prioritizes the IP networking aspects, but everything should be supported.

§This crate

This module decodes and encodes a Network Service Access Point (NSAP) to and from the “preferred binary encoding” described in Annex A, Section A.5.3 of ITU-T Recommendation X.213 (2001).

In addition to this, it displays and decodes NSAPs to and from human-readable strings according to the procedures defined in IETF RFC 1278, drawing on additional information found in IETF RFC 1277.

There are some deviations to the above, however. Since the human-friendly string syntax was defined, new AFIs were added, including one for directly representing IP addresses and another for representing URLs. As such this library extends the specification, but should be completely backwards compatible with it.

You should not expect an NSAP decoded from a string to encode back into the same exact string. You should not expect an NSAP decoded from bytes to encode back into the same exact bytes. You should not expect all NSAP syntaxes to be recognized everywhere; your application and dependencies should handle unrecognized NSAP syntaxes gracefully.

This crate is no_std and supports almost everything with no alloc as well; the only thing alloc gives you is better URL encoding and decoding, per ITU-T Recommendation X.519. Only extremely short URLs are supported without alloc.

§Usage

An NSAP address is represented using X213NetworkAddress. You can construct this using several methods:

X213NetworkAddress::from_vec()
X213NetworkAddress::from_vec_unchecked()
X213NetworkAddress::from_slice()
X213NetworkAddress::from_slice_unchecked()
X213NetworkAddress::from_ip()
X213NetworkAddress::from_ipv4()
X213NetworkAddress::from_ipv6()
X213NetworkAddress::from_itot_url()
X213NetworkAddress::from_non_osi_url()
X213NetworkAddress::from_itot_socket_addr()
X213NetworkAddress::try_from() (for Vec<u8> or &[u8])
X213NetworkAddress::from_str()
X213NetworkAddress::from() (for &IpAddr, &Ipv4Addr, or &Ipv6Addr)

The X213NetworkAddress type implements Display, which prints the NSAP address according to IETF RFC 1278.

If you need to pass NSAP addresses between heterogeneous systems, consider using to_ns_string or fmt_as_ns_string() instead. This will always encode the NSAP address using the NS+ syntax like: NS+A433BB93C1. These are not human-friendly, but they are really easy to parse and completely unambiguous.

There is no way in this crate to compare two NSAP addresses. The rationale for this is documented along with X213NetworkAddress, but if you want to compare the addresses byte-for-byte, you can use get_octets(), like so:

assert_eq!(addr1.get_octets(), addr2.get_octets());

This crate also supports several functions for working specifically with IP networking, above and beyond those already named, which are:

X213NetworkAddress::get_url()
X213NetworkAddress::get_ip()
X213NetworkAddress::get_rfc1277_socket()

In a TCP/IP only environment, you’ll likely want to invoke all three of these methods until one of them returns a result, then perform the appropriate connection setup.

Here is an example usage of this crate:

extern crate alloc;
use alloc::vec::Vec;
use nsap_address::X213NetworkAddress;
use nsap_address::AFI_F69_DEC_LEADING_ZERO;
use core::net::{IpAddr, Ipv4Addr};
use core::str::FromStr;

let addrstr = "TELEX+00728722+RFC-1006+03+255.0.0.2+65535+2";
let addr = X213NetworkAddress::from_str(addrstr).unwrap();
let (_, sock, _) = addr.get_rfc1277_socket().unwrap();
assert_eq!(sock.ip(), &Ipv4Addr::new(255, 0, 0, 2));
assert_eq!(sock.port(), 65535);
let idi_digits: Vec<u8> = addr.idi_digits().unwrap().collect();
assert_eq!(idi_digits.as_slice(), &[ 0, 0, 7, 2, 8, 7, 2, 2 ]);
assert_eq!(addr.get_octets(), &[
  AFI_F69_DEC_LEADING_ZERO, // AFI
  0x00, 0x72, 0x87, 0x22, // Telex 00728722
  0x03, // Network prefix (0x03 = Internet)
  0x25, 0x50, 0x00, 0x00, 0x00, 0x02, // IP address
  0x65, 0x53, 0x50, 0x00, 0x02, // port + tset
]);
let ns_string = addr.to_ns_string();
assert_eq!(ns_string.as_str(), "NS+5400728722032550000000026553500002");

§Feature Flags

alloc: heap allocation, which enables URL encoding and decoding for URLs
x25: Parsing of X.25 DSP strings, per IETF RFC 1278
ecma117: Parsing of ECMA 177 DSP strings, per IETF RFC 1278
nonstd: Parsing for non-standard syntaxes: those defined by this crate, but not in any standard, which are the IP4, IP6, URL, ICP, and IND.
nonstddisplay: implementation of std::fmt::Display for the above non-standard syntaxes. This is a separate feature flag so that, if you have an application that passes NSAPs as strings, you can ensure that you only use standardized syntaxes, while still being able to parse the non-standard ones.

alloc is the only one enabled by default. Keeping x25 off is a good idea unless, somehow, you are still using or working with X.25 networks. The ECMA 117 syntax was not widely used, so you are unlikely to encounter that as well; for this reason, you might want to keep ecma117 off. nonstd and nonstddisplay will be big quality-of-life improvements for you in almost all cases.

§AI Usage Statement

No code, tests, or documentation was produced by AI or an LLM of any kind, except for two small internal functions in utils, which were reviewed by the crate’s author.

§Deviations from IETF RFC 1278

ICP and IND AFIs recognized in the <afi>-<idi>-<dsp> syntax
IP4, IP6, and URL schemes supported in FromStr and Display

§To Do (Future)

Support GOSIP NSAP addressing
likely / unlikely branch prediction macros

Structs§

BCDBuffer: Buffer for writing Binary-Coded Decimal (BCD)
BCDDigitsIter: BCD Digits Iterator
X213NetworkAddressInfo: information about a particular NSAP syntax and what network it addresses

Enums§

DSPSyntax: X.213 NSAP Domain-Specific Part Syntax
NAddressParseError: An error parsing an NSAP address from bytes
RFC1278ParseError: Error representing an issue parsing an IETF RFC 1278 NSAP address string
X213NetworkAddress: ITU-T Recommendation X.213 NSAP Address
X213NetworkAddressType: X.213 NSAP network address type

Constants§

AFI_E163_BIN_LEADING_NON_ZERO: AFI for E.163 number (used in PSTN), binary, leading non-zero digit
AFI_E163_BIN_LEADING_ZERO: AFI for E.163 number (used in PSTN), binary, leading zero digit
AFI_E163_DEC_LEADING_NON_ZERO: AFI for E.163 number (used in PSTN), decimal, leading non-zero digit
AFI_E163_DEC_LEADING_ZERO: AFI for E.163 number (used in PSTN), decimal, leading zero digit
AFI_E164_BIN_LEADING_NON_ZERO: AFI for E.164 number (used in ISDN), binary, leading non-zero digit
AFI_E164_BIN_LEADING_ZERO: AFI for E.164 number (used in ISDN), binary, leading zero digit
AFI_E164_DEC_LEADING_NON_ZERO: AFI for E.164 number (used in ISDN), decimal, leading non-zero digit
AFI_E164_DEC_LEADING_ZERO: AFI for E.164 number (used in ISDN), decimal, leading zero digit
AFI_F69_BIN_LEADING_NON_ZERO: AFI for F.69 / Telex, binary, leading non-zero digit
AFI_F69_BIN_LEADING_ZERO: AFI for F.69 / Telex, binary, leading zero digit
AFI_F69_DEC_LEADING_NON_ZERO: AFI for F.69 / Telex, decimal, leading non-zero digit
AFI_F69_DEC_LEADING_ZERO: AFI for F.69 / Telex, decimal, leading zero digit
AFI_IANA_ICP_BIN: AFI for IANA Internet Code Point (ICP), binary, per IETF RFFC 4548
AFI_IANA_ICP_DEC: AFI for IANA Internet Code Point (ICP), decimal, per IETF RFFC 4548
AFI_ISO_6523_ICD_BIN: AFI for ISO/IEC 6523 International Code Designator (ICD), binary
AFI_ISO_6523_ICD_DEC: AFI for ISO/IEC 6523 International Code Designator (ICD), decimal
AFI_ISO_DCC_BIN: AFI for ISO Data Country Code (DCC) binary
AFI_ISO_DCC_DEC: AFI for ISO Data Country Code (DCC) decimal
AFI_ITU_T_IND_BIN: AFI for ITU Rec. E.191.1 International Network Designator (IDN), decimal
AFI_ITU_T_IND_DEC: AFI for ITU Rec. E.191.1 International Network Designator (IDN), decimal
AFI_LOCAL_BIN: Local AFI, binary
AFI_LOCAL_DEC: Local AFI, decimal
AFI_LOCAL_ISO_IEC_646: Local AFI, ISO/IEC 646 (ASCII or ASCII-like)
AFI_LOCAL_NATIONAL: Local AFI, characters from a national character set
AFI_STR_DCC: AFI string for ISO DCC addressing, per IETF RFC 1278
AFI_STR_ICD: AFI string for ISO/IEC 6523 ICD addressing, per IETF RFC 1278
AFI_STR_ICP: Not-standard AFI string for IANA ICP addressing
AFI_STR_IND: Not-standard AFI string for ITU-T IND addressing
AFI_STR_ISDN: AFI string for ISDN / E.164 addressing, per IETF RFC 1278
AFI_STR_LOCAL: AFI string for local addressing, per IETF RFC 1278
AFI_STR_PSTN: AFI string for PSTN / E.163 addressing, per IETF RFC 1278
AFI_STR_TELEX: AFI string for Telex / F.69 addressing, per IETF RFC 1278
AFI_STR_URL: Not-standard AFI string for ITU-T Rec. X.519 URL-based addressing
AFI_STR_X121: AFI string for X.121 addressing, per IETF RFC 1278
AFI_URL: The URL AFI defined in ITU-T Recommendation X.519 (2019).
AFI_X121_BIN_LEADING_NON_ZERO: AFI for an X.121 Address (used for X.25), binary, leading non-zero digit
AFI_X121_BIN_LEADING_ZERO: AFI for an X.121 Address (used for X.25), binary, leading zero digit
AFI_X121_DEC_LEADING_NON_ZERO: AFI for an X.121 Address (used for X.25), decimal, leading non-zero digit
AFI_X121_DEC_LEADING_ZERO: AFI for an X.121 Address (used for X.25), decimal, leading zero digit
DEFAULT_ITOT_TRANSPORT_SET: The default ISO Transport over TCP transport set (t-set) per IETF RFC 1277
ECMA_117_BINARY_STR: IETF RFC 1278 DSP string for ECMA 117 binary syntax
ECMA_117_DECIMAL_STR: IETF RFC 1278 DSP string for ECMA 117 decimal syntax
GROUP_AFI_E163_BIN_LEADING_NON_ZERO: Group AFI for AFI_E163_BIN_LEADING_NON_ZERO
GROUP_AFI_E163_BIN_LEADING_ZERO: Group AFI for AFI_E163_BIN_LEADING_ZERO
GROUP_AFI_E163_DEC_LEADING_NON_ZERO: Group AFI for AFI_E163_DEC_LEADING_NON_ZERO
GROUP_AFI_E163_DEC_LEADING_ZERO: Group AFI for AFI_E163_DEC_LEADING_ZERO
GROUP_AFI_E164_BIN_LEADING_NON_ZERO: Group AFI for AFI_E164_BIN_LEADING_NON_ZERO
GROUP_AFI_E164_BIN_LEADING_ZERO: Group AFI for AFI_E164_BIN_LEADING_ZERO
GROUP_AFI_E164_DEC_LEADING_NON_ZERO: Group AFI for AFI_E164_DEC_LEADING_NON_ZERO
GROUP_AFI_E164_DEC_LEADING_ZERO: Group AFI for AFI_E164_DEC_LEADING_ZERO
GROUP_AFI_F69_BIN_LEADING_NON_ZERO: Group AFI for AFI_F69_BIN_LEADING_NON_ZERO
GROUP_AFI_F69_BIN_LEADING_ZERO: Group AFI for AFI_F69_BIN_LEADING_ZERO
GROUP_AFI_F69_DEC_LEADING_NON_ZERO: Group AFI for AFI_F69_DEC_LEADING_NON_ZERO
GROUP_AFI_F69_DEC_LEADING_ZERO: Group AFI for AFI_F69_DEC_LEADING_ZERO
GROUP_AFI_IANA_ICP_BIN: Group AFI for AFI_IANA_ICP_BIN
GROUP_AFI_IANA_ICP_DEC: Group AFI for AFI_IANA_ICP_DEC
GROUP_AFI_ISO_6523_ICD_BIN: Group AFI for AFI_ISO_6523_ICD_BIN
GROUP_AFI_ISO_6523_ICD_DEC: Group AFI for AFI_ISO_6523_ICD_DEC
GROUP_AFI_ISO_DCC_BIN: Group AFI for AFI_ISO_DCC_BIN
GROUP_AFI_ISO_DCC_DEC: Group AFI for AFI_ISO_DCC_DEC
GROUP_AFI_ITU_T_IND_BIN: Group AFI for AFI_ITU_T_IND_BIN
GROUP_AFI_ITU_T_IND_DEC: Group AFI for AFI_ITU_T_IND_DEC
GROUP_AFI_LOCAL_BIN: Group AFI for AFI_LOCAL_BIN
GROUP_AFI_LOCAL_DEC: Group AFI for AFI_LOCAL_DEC
GROUP_AFI_LOCAL_ISO_IEC_646: Group AFI for AFI_LOCAL_ISO_IEC_646
GROUP_AFI_LOCAL_NATIONAL: Group AFI for AFI_LOCAL_NATIONAL
GROUP_AFI_X121_BIN_LEADING_NON_ZERO: Group AFI for AFI_X121_BIN_LEADING_NON_ZERO
GROUP_AFI_X121_BIN_LEADING_ZERO: Group AFI for AFI_X121_BIN_LEADING_ZERO
GROUP_AFI_X121_DEC_LEADING_NON_ZERO: Group AFI for AFI_X121_DEC_LEADING_NON_ZERO
GROUP_AFI_X121_DEC_LEADING_ZERO: Group AFI for AFI_X121_DEC_LEADING_ZERO
IANA_ICP_IDI_IPV4: IANA-allocated Internet Code Point for IPv4 per IETF RFC 4548
IANA_ICP_IDI_IPV6: IANA-allocated Internet Code Point for IPv6 per IETF RFC 4548
IETF_RFC_1006_PREFIX_STR: IETF RFC 1278 DSP string for ISO Transport over TCP (ITOT)
IETF_RFC_1277_TELEX_NUMBER_STR: IETF RFC 1277 Telex / F.69 number for non-OSI networks
IPV4_STR: Non-standard string for NSAP-encoded IPv4 addresses
IPV6_STR: Non-standard string for NSAP-encoded IPv6 addresses
ITOT_OVER_IPV4_DEFAULT_PORT: Default TCP port for ISO Transport over TCP (ITOT) per IETF RFC 2126
ITU_X519_DSP_PREFIX_IDM_OVER_IPV4: ITU-T Rec. X.519 DSP prefix for IDM over IPv4
ITU_X519_DSP_PREFIX_ITOT_OVER_IPV4: ITU-T Rec. X.519 DSP prefix for ISO Transport over TCP (ITOT) over IPv4
ITU_X519_DSP_PREFIX_LDAP: ITU-T Rec. X.519 DSP prefix for LDAP
MAX_BIN_DSP_LEN_E163: Maximum binary DSP length in bytes for E.163 / PSTN addressing
MAX_BIN_DSP_LEN_E164: Maximum binary DSP length in bytes for E.164 / ISDN addressing
MAX_BIN_DSP_LEN_F69: Maximum binary DSP length in bytes for F.69 addressing / Telex
MAX_BIN_DSP_LEN_IANA_ICP: Maximum binary DSP length in bytes for IANA ICP (IPv4 or IPv6) addressing
MAX_BIN_DSP_LEN_ISO_6523_ICD: Maximum binary DSP length in bytes for ISO/IEC 6523 ICD addressing
MAX_BIN_DSP_LEN_ISO_DCC: Maximum binary DSP length in bytes for ISO DCC
MAX_BIN_DSP_LEN_ITU_T_IND: Maximum binary DSP length in bytes for ITU-T IND addressing
MAX_BIN_DSP_LEN_LOCAL: Maximum binary DSP length in bytes for local addressing
MAX_BIN_DSP_LEN_X121: Maximum binary DSP length in bytes for X.121 / X.25 addressing
MAX_DEC_DSP_LEN_DIGITS_E163: Maximum decimal DSP length in digits for E.163 / PSTN addressing
MAX_DEC_DSP_LEN_DIGITS_E164: Maximum decimal DSP length in digits for E.164 / ISDN addressing
MAX_DEC_DSP_LEN_DIGITS_F69: Maximum decimal DSP length in digits for F.69 addressing / Telex
MAX_DEC_DSP_LEN_DIGITS_IANA_ICP: Maximum decimal DSP length in digits for IANA ICP (IPv4 or IPv6) addressing
MAX_DEC_DSP_LEN_DIGITS_ISO_6523_ICD: Maximum decimal DSP length in digits for ISO/IEC 6523 ICD addressing
MAX_DEC_DSP_LEN_DIGITS_ISO_DCC: Maximum decimal DSP length in digits for ISO DCC
MAX_DEC_DSP_LEN_DIGITS_ITU_T_IND: Maximum decimal DSP length in digits for ITU-T IND addressing
MAX_DEC_DSP_LEN_DIGITS_LOCAL: Maximum decimal DSP length in digits for local addressing
MAX_DEC_DSP_LEN_DIGITS_X121: Maximum decimal DSP length in digits for X.121 / X.25 addressing
MAX_IDI_LEN_DIGITS_E163: Maximum IDI length in digits for E.163 / PSTN addressing
MAX_IDI_LEN_DIGITS_E164: Maximum IDI length in digits for E.164 / ISDN addressing
MAX_IDI_LEN_DIGITS_F69: Maximum IDI length in digits for F.69 addressing / Telex
MAX_IDI_LEN_DIGITS_IANA_ICP: Maximum IDI length in digits for IANA ICP (IPv4 or IPv6) addressing
MAX_IDI_LEN_DIGITS_ISO_6523_ICD: Maximum IDI length in digits for ISO/IEC 6523 ICD addressing
MAX_IDI_LEN_DIGITS_ISO_DCC: Maximum IDI length in digits for ISO DCC
MAX_IDI_LEN_DIGITS_ITU_T_IND: Maximum IDI length in digits for ITU-T IND addressing
MAX_IDI_LEN_DIGITS_LOCAL: Maximum IDI length in digits for local addressing
MAX_IDI_LEN_DIGITS_URL: Maximum IDI length in digits for ITU-T Rec. X.519 URL NSAPs
MAX_IDI_LEN_DIGITS_X121: Maximum IDI length in digits for X.121 / X.25 addressing
MAX_ISO_IEC_646_LEN_LOCAL: Maximum ISO/IEC 646-encoded DSP length in bytes for local addressing
MAX_NATIONAL_CHAR_LEN_LOCAL: Maximum national character-encoded DSP length in bytes for local addressing
RFC_1277_PREFIX: IETF RFC 1277 NSAP prefix for non-OSI addressing
RFC_1277_WELL_KNOWN_NETWORK_DARPA_NSF_INTERNET: IETF RFC 1277 well-known network: DARPA/NSF Internet (The internet)
RFC_1277_WELL_KNOWN_NETWORK_INTL_X25: IETF RFC 1277 well-known network: International X.25
RFC_1277_WELL_KNOWN_NETWORK_IXI: IETF RFC 1277 well-known network: IXI
RFC_1277_WELL_KNOWN_NETWORK_JANET: IETF RFC 1277 well-known network: JANET
SMALLEST_VALID_NSAP_ADDR: The AFI is mandatory. The IDI may be zero bytes (in the case of Local IDI), and the DSP (presumably) MUST be present.
X25_PREFIX_STR: IETF RFC 1278 DSP string for X.25

Functions§

afi_to_network_type: Return get the N-address network type from the AFI
char_to_local_iso_iec_646_byte: Convert a UTF-8 char to an ISO/IEC 646 byte per ITU-T Rec. X.213
get_nsap_address_schema: Get information about the NSAP syntax and network type by AFI
is_group_afi: Returns true if an AFI is a group AFI
is_individual_afi: Returns true if an AFI is an individual AFI
local_iso_iec_646_byte_to_char: Convert an ISO/IEC 646 byte encoded per ITU-T Rec. X.213 to a UTF-8 char

Type Aliases§

AFI: Authority and Format Identifier (AFI): part of an NSAP address
Rfc1277NetworkId: Network identifier, encoded as Binary-Coded Decimal (BCD), per IETF RFC 1277
Rfc1277SocketInfo: Socket information, per IETF RFC 1277
Rfc1277TransportSet: Transport set, per IETF RFC 1277
ShouldBeASCIIDigit: An ASCII digit (0x30..=0x39)