Module message 

STUN Messages

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

Message parsing is zerocopy by default through the RawAttribute struct. Converting to a concrete attribute implementation (e.g. Software) may incur a copy depending on the attribute implementation.

The destination for a written Message is completely customizable through the MessageWrite trait. It is therefore possible to write directly into network provided buffers for increased performance and throughput.

Examples

Parse a STUN Message

use stun_types::prelude::*;
use stun_types::attribute::{RawAttribute, PasswordAlgorithm, PasswordAlgorithmValue};
use stun_types::message::{Message, MessageType, MessageClass, BINDING};

let msg_data = [
    0x00, 0x01, 0x00, 0x08, // method, class and length
    0x21, 0x12, 0xA4, 0x42, // Fixed STUN magic bytes
    0x00, 0x00, 0x00, 0x00, // \
    0x00, 0x00, 0x00, 0x00, // } transaction ID
    0x00, 0x00, 0x73, 0x92, // /
    0x00, 0x1D, 0x00, 0x04, // PasswordAlgorithm attribute header (type and length)
    0x00, 0x02, 0x00, 0x00  // PasswordAlgorithm attribute value
];
let msg = Message::from_bytes(&msg_data).unwrap();

// the various parts of a message can be retreived
assert_eq!(msg.get_type(), MessageType::from_class_method(MessageClass::Request, BINDING));
assert_eq!(msg.transaction_id(), 0x7392.into());

// Attributes can be retrieved as raw values.
let msg_attr = msg.raw_attribute(0x1D.into()).unwrap();
let attr = RawAttribute::new(0x1D.into(), &[0, 2, 0, 0]);
assert_eq!(msg_attr, attr);

// Or as typed values
let attr = msg.attribute::<PasswordAlgorithm>().unwrap();
assert_eq!(attr.algorithm(), PasswordAlgorithmValue::SHA256);

Generating a Message

use stun_types::prelude::*;
use stun_types::attribute::Software;
use stun_types::message::{Message, MessageWriteVec, BINDING};

// Automatically generates a transaction ID.
let mut msg = Message::builder_request(BINDING, MessageWriteVec::new());

let software_name = "stun-types";
let software = Software::new(software_name).unwrap();
assert_eq!(software.software(), software_name);
msg.add_attribute(&software).unwrap();

let attribute_data = [
    0x80, 0x22, 0x00, 0x0a, // attribute type (0x8022) 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 msg_data = msg.finish();
// ignores the randomly generated transaction id
assert_eq!(msg_data[20..], attribute_data);

Structs

IntegrityKey

A cached key for a particular set of credentials.

LongTermCredentials

Structure for holding the required credentials for long-term STUN credentials.

LongTermKeyCredentials

Structure for holding the required long term credentials for signing STUN messages.

Message

The structure that encapsulates the entirety of a STUN message.

MessageHeader

The fixed length header of a STUN message.

MessageType

The type of a Message. A combination of a MessageClass and a STUN method.

MessageWriteMutSlice

A MessageWrite implementation that writes into a mutable slice.

MessageWriteVec

A MessageWrite implementation that writes into a Vec<u8>.

Method

The method in a STUN Message.

ShortTermCredentials

Structure for holding the required credentials for handling short-term STUN credentials.

TransactionId

A unique transaction identifier for each message and it’s (possible) response.

Enums

IntegrityAlgorithm

The supported hashing algorithms for ensuring integrity of a Message

MessageClass

The class of a Message.

MessageIntegrityCredentials

Enum for holding the credentials used to sign or verify a Message

StunParseError

Possible errors when parsing a STUN message.

StunWriteError

Errors produced when writing a STUN message.

ValidateError

Errors produced when validating a STUN message.

Constants

BINDING

The value of the binding message type. Can be used in either a request or an indication message.

MAGIC_COOKIE

The value of the magic cookie (in network byte order) as specified in RFC5389, and RFC8489.

Traits

MessageWrite

Trait for implementing a writer for Messages.

MessageWriteExt

Extension trait for MessageWrite providing helper functions.