Crate stun_rs

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).
• RFC8016. Mobility with Traversal Using Relays around NAT (TURN).

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).
• mobility: Extends support for parsing attributes defined in RFC8016. Mobility with Traversal Using Relays around NAT (TURN).
• 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::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
• protocols
  Assigned Internet Protocol Numbers. This module contains the protocol numbers specified in PROTOCOL-NUMBERS.

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.
• StunPadding
  Custom padding used to encode a message. This feature required to enable the flag experiments

Constants

• MAGIC_COOKIE
  STUN magic cookie
• MESSAGE_HEADER_SIZE
  STUN message header size

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.