Module attribute

Expand description

STUN Attributes

Provides implementations for generating, parsing and manipulating STUN attributes as specified in one of RFC8489, RFC5389, or RFC3489.

There are two levels of attribute implementations:

A generic RawAttribute which contains the AttributeHeader (type and length) and the byte sequence of data (either borrowed or owned). Parsing a Message will only perform zerocopy parsing to this level. Any attribute-specific restrictions on the actual contents of the data should be performed by concrete attribute implementations.
Concrete implementations based on implementing Attribute, and AttributeStaticType. These concrete attribute implementations have much more ergonomic API specific to their particular needs. A concrete attribute implementation may have restrictions on what data is allowed to be parsed from a RawAttribute that should return errors when calling AttributeFromRaw::from_raw_ref.

§Examples

§Parse and write an already defined `Attribute`

use stun_types::attribute::{RawAttribute, Software};
let software_name = "stun-types";
let software = Software::new(software_name).unwrap();
assert_eq!(software.software(), software_name);

let attribute_data = [
    0x80, 0x22, 0x00, 0x0a, // Attribute type (0x8022: Software) and length (0x000a)
    0x73, 0x74, 0x75, 0x6E, // s t u n
    0x2D, 0x74, 0x79, 0x70, // - t y p
    0x65, 0x73, 0x00, 0x00  // e s
];

let raw = RawAttribute::from(&software);
assert_eq!(raw.to_bytes(), attribute_data);

// Can also parse data into a typed attribute as needed
let software = Software::from_raw(raw).unwrap();
assert_eq!(software.software(), software_name);

§Defining your own `Attribute`

use byteorder::{BigEndian, ByteOrder};
use stun_types::attribute::{AttributeType, RawAttribute};
use stun_types::message::StunParseError;
#[derive(Debug)]
struct MyAttribute {
   value: u32,
}
impl AttributeStaticType for MyAttribute {
   const TYPE: AttributeType = AttributeType::new(0x8851);
}
impl Attribute for MyAttribute {
   fn get_type(&self) -> AttributeType {
       Self::TYPE
   }

   fn length(&self) -> u16 {
       4
   }
}
impl AttributeWrite for MyAttribute {
    fn to_raw(&self) -> RawAttribute<'_> {
        let mut ret = [0; 4];
        BigEndian::write_u32(&mut ret, self.value);
        RawAttribute::new(MyAttribute::TYPE, &ret).into_owned()
    }
    fn write_into_unchecked(&self, dest: &mut [u8]) {
        self.write_header_unchecked(dest);
        BigEndian::write_u32(&mut dest[4..], self.value);
    }
}
impl AttributeFromRaw<'_> for MyAttribute {
    fn from_raw_ref(raw: &RawAttribute) -> Result<Self, StunParseError>
    where
        Self: Sized,
    {
        raw.check_type_and_len(Self::TYPE, 4..=4)?;
        let value = BigEndian::read_u32(&raw.value);
        Ok(Self {
            value,
        })
    }
}

// Optional: if you want this attribute to be displayed nicely when the corresponding
// `RawAttribute` (based on `AttributeType`) is formatted using `RawAttribute`'s `Display`
// implementation.
impl std::fmt::Display for MyAttribute {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "MyAttribute: {}", self.value)
    }
}
stun_types::attribute_display!(MyAttribute);
MyAttribute::TYPE.add_name("MY-ATTRIBUTE");

let my_attr = MyAttribute { value: 0x4729 };
let raw = RawAttribute::from(&my_attr);

let attribute_data = [
    0x88, 0x51, 0x00, 0x04,
    0x00, 0x00, 0x47, 0x29,
];
assert_eq!(raw.to_bytes(), attribute_data);

let my_attr = MyAttribute::from_raw(raw).unwrap();
assert_eq!(my_attr.value, 0x4729);

Structs§

AlternateDomain: The AlternateDomain Attribute
AlternateServer: The AlternateServer Attribute
AttributeHeader: Structure for holding the header of a STUN attribute. Contains the type and the length
AttributeType: The type of an Attribute in a STUN Message
ErrorCode: The ErrorCode Attribute
Fingerprint: The Fingerprint Attribute
IceControlled: The IceControlled Attribute
IceControlling: The IceControlling Attribute
MappedSocketAddr: Helper struct for SocketAddrs that are stored as an attribute.
MessageIntegrity: The MessageIntegrity Attribute
MessageIntegritySha256: The MessageIntegritySha256 Attribute
Nonce: The Nonce Attribute
PasswordAlgorithm: The PasswordAlgorithm Attribute
PasswordAlgorithms: The PasswordAlgorithms Attribute
Priority: The Priority Attribute
RawAttribute: The header and raw bytes of an unparsed Attribute
Realm: The Realm Attribute
Software: The Software Attribute
UnknownAttributes: The UnknownAttributes Attribute
UseCandidate: The UseCandidate Attribute
Userhash: The Userhash Attribute
Username: The username Attribute
XorMappedAddress: The XorMappedAddress Attribute
XorSocketAddr: Helper struct for SocketAddr that are stored as an Attribute after an XOR operation with the TransactionId of a Message.

Enums§

AddressFamily: The address family of the socket
PasswordAlgorithmValue: The hashing algorithm for the password

Traits§

Attribute: A STUN attribute for use in Messages
AttributeExt: Automatically implemented trait providing some helper functions for Attributes.
AttributeFromRaw: A trait for converting from a RawAttribute to a concrete Attribute.
AttributeStaticType: A static type for an Attribute
AttributeWrite: Trait required when implementing writing an Attribute to a sequence of bytes
AttributeWriteExt: Automatically implemented trait providing helper functionality for writing an Attribute to a sequence of bytes.

Functions§

add_display_impl: Adds an externally provided Display implementation for a particular AttributeType. Any previous implementation is overidden.

Type Aliases§

AttributeDisplay: A closure definition for an externally provided Display implementation for a RawAttribute.

Module attributeCopy item path