Crate stun_rs

Expand description

STUN library.

This crate provides a simple framework to manage STUN protocol. The implementation is based on:

RFC8489. Session Traversal Utilities for NAT (STUN).
RFC8445. Interactive Connectivity Establishment (ICE).
RFC8656. Traversal Using Relays around NAT (TURN)
RFC5769. Test Vectors for Session Traversal Utilities for NAT (STUN).

Usage

Example that creates and encodes a STUN Binding request

 // Create attributes
 let username = UserName::new("\u{30DE}\u{30C8}\u{30EA}\u{30C3}\u{30AF}\u{30B9}")?;
 let nonce = Nonce::new("f//499k954d6OL34oL9FSTvy64sA")?;
 let realm = Realm::new("example.org")?;
 let password = "TheMatrIX";
 let algorithm = Algorithm::from(AlgorithmId::MD5);
 let key = HMACKey::new_long_term(&username, &realm, password, algorithm)?;
 let integrity = MessageIntegrity::new(key);

 // Create the message
 let msg = StunMessageBuilder::new(
   BINDING,
   MessageClass::Request,
 )
 .with_attribute(username)
 .with_attribute(nonce)
 .with_attribute(realm)
 .with_attribute(integrity)
 .build();

 // Create an encoder to encode the message into a buffer
 let encoder = MessageEncoderBuilder::default().build();
 let mut buffer: [u8; 150] = [0x00; 150];
 let size = encoder.encode(&mut buffer, &msg)?;
 assert_eq!(size, 116);

Example that decodes a STUN Binding response and fetches some attributes.

 // This response uses the following parameter:
 // Password: `VOkJxbRl1RmTxUk/WvJxBt` (without quotes)
 // Software name: "test vector" (without quotes)
 // Mapped address: 192.0.2.1 port 32853
 let sample_ipv4_response = [
     0x01, 0x01, 0x00, 0x3c, // Response type and message length
     0x21, 0x12, 0xa4, 0x42, // Magic cookie
     0xb7, 0xe7, 0xa7, 0x01, // }
     0xbc, 0x34, 0xd6, 0x86, // }  Transaction ID
     0xfa, 0x87, 0xdf, 0xae, // }
     0x80, 0x22, 0x00, 0x0b, // SOFTWARE attribute header
     0x74, 0x65, 0x73, 0x74, // }
     0x20, 0x76, 0x65, 0x63, // }  UTF-8 server name
     0x74, 0x6f, 0x72, 0x20, // }
     0x00, 0x20, 0x00, 0x08, // XOR-MAPPED-ADDRESS attribute header
     0x00, 0x01, 0xa1, 0x47, // Address family (IPv4) and xor'd mapped port number
     0xe1, 0x12, 0xa6, 0x43, // Xor'd mapped IPv4 address
     0x00, 0x08, 0x00, 0x14, // MESSAGE-INTEGRITY header
     0x2b, 0x91, 0xf5, 0x99, // }
     0xfd, 0x9e, 0x90, 0xc3, // }
     0x8c, 0x74, 0x89, 0xf9, // } HMAC-SHA1 fingerprint
     0x2a, 0xf9, 0xba, 0x53, // }
     0xf0, 0x6b, 0xe7, 0xd7, // }
     0x80, 0x28, 0x00, 0x04, // FINGERPRINT attribute header
     0xc0, 0x7d, 0x4c, 0x96, // Reserved for CRC32 fingerprint
 ];

 // Create a STUN decoder context using the password as a short credential
 // mechanism and force validation of MESSAGE-INTEGRITY and FINGERPRINT
 let ctx = DecoderContextBuilder::default()
   .with_key(
     HMACKey::new_short_term("VOkJxbRl1RmTxUk/WvJxBt")?,
   )
   .with_validation()
   .build();
 let decoder = MessageDecoderBuilder::default().with_context(ctx).build();

 let (msg, size) = decoder.decode(&sample_ipv4_response)?;
 assert_eq!(size, sample_ipv4_response.len());

 // Check message method is a BINDING response
 assert_eq!(msg.method(), BINDING);
 assert_eq!(msg.class(), MessageClass::SuccessResponse);

 let software = msg.get::<Software>()
   .ok_or("Software attribute not found")?
   .as_software()?;
 assert_eq!(software, "test vector");

 let xor_addr = msg.get::<XorMappedAddress>()
   .ok_or("XorMappedAddress attribute not found")?
   .as_xor_mapped_address()?;
 let socket = xor_addr.socket_address();
 assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)));
 assert_eq!(socket.port(), 32853);
 assert!(socket.is_ipv4());

Common features

This crate defines next feature flags that can be enabled:

turn: Extends support for parsing attributes defined in RFC8656. Traversal Using Relays around NAT (TURN)
ice: Extends support for parsing attributes defined in RFC8445. Interactive Connectivity Establishment (ICE).
experiments: This flag can be set to adjust some behavior of the library, such as default padding. When testing protocols, we can use this flag to force the library to keep the data associated with Unknown attributes. By default, Unknown attributes store no data to save memory consumption.

Re-exports

pub use crate::attributes::AttributeType;

pub use crate::attributes::StunAttribute;

pub use crate::attributes::StunAttributeType;

pub use crate::attributes::Verifiable;

pub use crate::error::StunError;

pub use crate::error::StunErrorType;

Modules

attributes

STUN Attributes. This module contains all attributes defined for the STUN protocol. Additional flags can be enabled for TURN and ICE.

error

STUN Errors. This module contains all errors that can happen when dealing with stun.

methods

STUN Methods Registry

Structs

Algorithm

An algorithm is the combination of the AlgorithmId and its parameters.

Cookie

STUN message cookie

DecoderContext

Context used to decode STUN messages

DecoderContextBuilder

Builder class used to construct DecoderContext objects

EncoderContext

Context used to decode STUN messages that requires special treatment like CRC or integrity validations

EncoderContextBuilder

Builder class used to construct EncoderContext objects

ErrorCode

The ErrorCode contains a numeric error code value in the range of 300 to 699 plus a textual reason phrase encoded in UTF-8 RFC3629; it is also consistent in its code assignments and semantics with SIP RFC3261 and HTTP RFC7231. The reason phrase is meant for diagnostic purposes and can be anything appropriate for the error code. Recommended reason phrases for the defined error codes are included in the IANA registry for error codes. The reason phrase MUST be a UTF-8-encoded RFC3629 sequence of fewer than 128 characters (which can be as long as 509 bytes when encoding them or 763 bytes when decoding them).

HMACKey

Key used for authentication and message integrity

MessageDecoder

Class used to decode STUN messages

MessageDecoderBuilder

Builder class used to create a stun MessageDecoder

MessageEncoder

Class used to encode STUN messages

MessageEncoderBuilder

Builder class used to create a stun MessageEncoder

MessageHeader

The STUN message header

MessageMethod

The STUN method is a 12 bits hex number in the range 0x000-0xFFF but valid values are defined in the range 0x00-0xFF. STUN methods in the range 0x000-0x07F are assigned by IETF Review RFC8126. STUN methods in the range 0x080-0x0FF are assigned by Expert Review.

MessageType

The message type defines the message class (request, success response, error response, or indication) and the message method (the primary function) of the STUN message. Although there are four message classes, there are only two types of transactions in STUN: request/response transactions (which consist of a request message and a response message) and indication transactions (which consist of a single indication message). Response classes are split into error and success responses to aid in quickly processing the STUN message.

StunMessage

The stun message is the basic unit of information interchanged between two agents implementing the STUN protocol.

StunMessageBuilder

The StunMessageBuilder ease the creation of a StunMessage

TransactionId

The transaction ID is a 96-bit identifier, used to uniquely identify STUN transactions. It primarily serves to correlate requests with responses, though it also plays a small role in helping to prevent certain types of attacks. The server also uses the transaction ID as a key to identify each transaction uniquely across all clients.

Enums

AddressFamily

Address family

AlgorithmId

STUN Password Algorithms

CredentialMechanism

Authentication and message-integrity mechanisms. The STUN RFC8489 defines two mechanisms for STUN that a client and server can use to provide authentication and message integrity; these two mechanisms are known as the short-term credential mechanism and the long-term credential mechanism. These two mechanisms are optional, and each usage must specify if and when these mechanisms are used.

MessageClass

The STUN message class. Although there are four message classes, there are only two types of transactions in STUN: request/response transactions (which consist of a request message and a response message) and indication transactions (which consist of a single indication message). Response classes are split into error and success responses to aid in quickly processing the STUN message.

Constants

MAGIC_COOKIE

STUN magic cookie

Functions

get_input_text

Gets the input text used by attributes that requires validation. The text used as input for validation is the STUN message, up to and including the attribute preceding the specified attribute. The Length field of the STUN message header is adjusted to point to the end of the value of this attribute.