Struct stun_coder::StunMessage
source · [−]pub struct StunMessage { /* private fields */ }
Expand description
An example of creating and encoding a STUN binding request:
// Create a request message
let message = stun_coder::StunMessage::create_request()
.add_attribute(stun_coder::StunAttribute::Software {
description: String::from("rust-stun-coder"),
})
.add_message_integrity()
.add_fingerprint();
// Encode it into bytes
let encoded_message = message.encode(Some("TEST_PASS")).unwrap();
println!("{:#X?}", encoded_message);
An example that decodes a sample request with Long-Term Authentication
// Encoded message
let msg_bytes: Vec<u8> = vec![
0x01, 0x01, 0x00, 0x48, 0x21, 0x12, 0xa4, 0x42, 0xb7, 0xe7, 0xa7, 0x01, 0xbc, 0x34,
0xd6, 0x86, 0xfa, 0x87, 0xdf, 0xae, 0x80, 0x22, 0x00, 0x0b, 0x74, 0x65, 0x73, 0x74,
0x20, 0x76, 0x65, 0x63, 0x74, 0x6f, 0x72, 0x00, 0x00, 0x20, 0x00, 0x14, 0x00, 0x02,
0xa1, 0x47, 0x01, 0x13, 0xa9, 0xfa, 0xa5, 0xd3, 0xf1, 0x79, 0xbc, 0x25, 0xf4, 0xb5,
0xbe, 0xd2, 0xb9, 0xd9, 0x00, 0x08, 0x00, 0x14, 0xBD, 0x3, 0x6D, 0x6A, 0x33, 0x17,
0x50, 0xDF, 0xE2, 0xED, 0xC5, 0x8E, 0x64, 0x34, 0x55, 0xCF, 0xF5, 0xC8, 0xE2, 0x64,
0x80, 0x28, 0x00, 0x04, 0x4F, 0x26, 0x02, 0x93,
];
// Integrity key used for verification
let integrity_key = Some("VOkJxbRl1RmTxUk/WvJxBt");
// Decode the message
let decoded_msg = stun_coder::StunMessage::decode(&msg_bytes, integrity_key).unwrap();
println!("{:?}", decoded_msg);
STUN messages are encoded in binary using network-oriented format (most significant byte or octet first, also commonly known as big- endian). The transmission order is described in detail in Appendix B of RFC0791. Unless otherwise noted, numeric constants are in decimal (base 10).
All STUN messages MUST start with a 20-byte header followed by zero or more Attributes. The STUN header contains a STUN message type, magic cookie, transaction ID, and message length.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0 0| STUN Message Type | Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic Cookie |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Transaction ID (96 bits) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 2: Format of STUN Message Header
The most significant 2 bits of every STUN message MUST be zeroes. This can be used to differentiate STUN packets from other protocols when STUN is multiplexed with other protocols on the same port.
The message type defines the message class (request, success response, failure 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.
The message type field is decomposed further into the following structure:
0 1
2 3 4 5 6 7 8 9 0 1 2 3 4 5
+--+--+-+-+-+-+-+-+-+-+-+-+-+-+
|M |M |M|M|M|C|M|M|M|C|M|M|M|M|
|11|10|9|8|7|1|6|5|4|0|3|2|1|0|
+--+--+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 3: Format of STUN Message Type Field
Here the bits in the message type field are shown as most significant (M11) through least significant (M0). M11 through M0 represent a 12- bit encoding of the method. C1 and C0 represent a 2-bit encoding of the class. A class of 0b00 is a request, a class of 0b01 is an indication, a class of 0b10 is a success response, and a class of 0b11 is an error response. This specification defines a single method, Binding. The method and class are orthogonal, so that for each method, a request, success response, error response, and indication are possible for that method. Extensions defining new methods MUST indicate which classes are permitted for that method.
For example, a Binding request has class=0b00 (request) and method=0b000000000001 (Binding) and is encoded into the first 16 bits as 0x0001. A Binding response has class=0b10 (success response) and method=0b000000000001, and is encoded into the first 16 bits as 0x0101.
Note: This unfortunate encoding is due to assignment of values in
[RFC3489](https://tools.ietf.org/html/rfc3489) that did not consider encoding Indications, Success, and
Errors using bit fields.
The magic cookie field MUST contain the fixed value 0x2112A442 in network byte order. In RFC3489, this field was part of the transaction ID; placing the magic cookie in this location allows a server to detect if the client will understand certain attributes that were added in this revised specification. In addition, it aids in distinguishing STUN packets from packets of other protocols when STUN is multiplexed with those other protocols on the same port.
The transaction ID is a 96-bit identifier, used to uniquely identify STUN transactions. For request/response transactions, the transaction ID is chosen by the STUN client for the request and echoed by the server in the response. For indications, it is chosen by the agent sending the indication. 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. As such, the transaction ID MUST be uniformly and randomly chosen from the interval 0 .. 2**96-1, and SHOULD be cryptographically random. Resends of the same request reuse the same transaction ID, but the client MUST choose a new transaction ID for new transactions unless the new request is bit-wise identical to the previous request and sent from the same transport address to the same IP address. Success and error responses MUST carry the same transaction ID as their corresponding request. When an agent is acting as a STUN server and STUN client on the same port, the transaction IDs in requests sent by the agent have no relationship to the transaction IDs in requests received by the agent.
The message length MUST contain the size, in bytes, of the message not including the 20-byte STUN header. Since all STUN attributes are padded to a multiple of 4 bytes, the last 2 bits of this field are always zero. This provides another way to distinguish STUN packets from packets of other protocols.
Following the STUN fixed portion of the header are zero or more attributes. Each attribute is TLV (Type-Length-Value) encoded. The details of the encoding, and of the attributes themselves are given in Section 15.
Implementations
sourceimpl StunMessage
impl StunMessage
sourceimpl StunMessage
impl StunMessage
sourcepub fn encode(
&self,
integrity_password: Option<&str>
) -> Result<Vec<u8>, MessageEncodeError>
pub fn encode(
&self,
integrity_password: Option<&str>
) -> Result<Vec<u8>, MessageEncodeError>
Encodes the STUN message into a binary representation
Arguments:
integrity_password
: Optionally set key that will be used for message integrity generation. Required if a MessageIntegrity attribute is present.
sourceimpl StunMessage
impl StunMessage
sourcepub fn new(method: StunMessageMethod, class: StunMessageClass) -> Self
pub fn new(method: StunMessageMethod, class: StunMessageClass) -> Self
Creates a new message
sourcepub fn create_request() -> Self
pub fn create_request() -> Self
Creates a Binding Request
sourcepub fn create_success_response() -> Self
pub fn create_success_response() -> Self
Creates a Binding Success Response
sourcepub fn create_error_response() -> Self
pub fn create_error_response() -> Self
Creates a Binding Error Response
sourcepub fn create_indication() -> Self
pub fn create_indication() -> Self
Creates a Binding Indication
sourcepub fn set_transaction_id(self, transaction_id: [u8; 12]) -> Self
pub fn set_transaction_id(self, transaction_id: [u8; 12]) -> Self
Sets message transaction id
sourcepub fn set_message_class(self, class: StunMessageClass) -> Self
pub fn set_message_class(self, class: StunMessageClass) -> Self
Sets message class
sourcepub fn set_message_method(self, method: StunMessageMethod) -> Self
pub fn set_message_method(self, method: StunMessageMethod) -> Self
Sets message method
sourcepub fn get_header(&self) -> &StunHeader
pub fn get_header(&self) -> &StunHeader
Returns an immutable reference to the message header
sourcepub fn get_attributes(&self) -> &Vec<StunAttribute>
pub fn get_attributes(&self) -> &Vec<StunAttribute>
Returns an immutable reference to the message attributes
sourcepub fn add_attribute(self, attr: StunAttribute) -> Self
pub fn add_attribute(self, attr: StunAttribute) -> Self
Adds an attribute to the list
sourcepub fn add_fingerprint(self) -> Self
pub fn add_fingerprint(self) -> Self
Adds a Fingerprint attribute at the end of the message
NOTE: This function should be invoked only when all other attributes are added
sourcepub fn add_message_integrity(self) -> Self
pub fn add_message_integrity(self) -> Self
Adds a MessageIntegrity attribute at the end of the message
NOTE: This function should be invoked only when all other attributes are added but before the Fingerprint attribute
sourcepub fn add_long_term_credential_message_integrity(
self,
username: &str,
realm: &str
) -> Result<Self, Error>
pub fn add_long_term_credential_message_integrity(
self,
username: &str,
realm: &str
) -> Result<Self, Error>
Adds USER, REALM and MESSAGE-INTEGRITY attributes for long term credential authentication
NOTE: This function should be invoked only when all other attributes are added but before the Fingerprint attribute
Trait Implementations
sourceimpl Clone for StunMessage
impl Clone for StunMessage
sourcefn clone(&self) -> StunMessage
fn clone(&self) -> StunMessage
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl Debug for StunMessage
impl Debug for StunMessage
sourceimpl Default for StunMessage
impl Default for StunMessage
Auto Trait Implementations
impl RefUnwindSafe for StunMessage
impl Send for StunMessage
impl Sync for StunMessage
impl Unpin for StunMessage
impl UnwindSafe for StunMessage
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more