Enum stun_coder::StunAttribute

source · [−]

pub enum StunAttribute {
Show 15 variants    MappedAddress {
        socket_addr: SocketAddr,
    },
    XorMappedAddress {
        socket_addr: SocketAddr,
    },
    Username {
        value: String,
    },
    MessageIntegrity {
        key: Vec<u8>,
    },
    Fingerprint {
        value: u32,
    },
    ErrorCode {
        class: u8,
        number: u8,
        reason: String,
    },
    Realm {
        value: String,
    },
    Nonce {
        value: String,
    },
    UnknownAttributes {
        types: Vec<u16>,
    },
    Software {
        description: String,
    },
    AlternateServer {
        socket_addr: SocketAddr,
    },
    Priority {
        value: u32,
    },
    UseCandidate,
    IceControlled {
        tie_breaker: u64,
    },
    IceControlling {
        tie_breaker: u64,
    },
}

Expand description

STUN message attribute

After the STUN header are zero or more attributes. Each attribute MUST be TLV encoded, with a 16-bit type, 16-bit length, and value. Each STUN attribute MUST end on a 32-bit boundary. As mentioned above, all fields in an attribute are transmitted most significant bit first. The value in the length field MUST contain the length of the Value part of the attribute, prior to padding, measured in bytes. Since STUN aligns attributes on 32-bit boundaries, attributes whose content is not a multiple of 4 bytes are padded with 1, 2, or 3 bytes of padding so that its value contains a multiple of 4 bytes. The padding bits are ignored, and may be any value.

Any attribute type MAY appear more than once in a STUN message. Unless specified otherwise, the order of appearance is significant: only the first occurrence needs to be processed by a receiver, and any duplicates MAY be ignored by a receiver.

To allow future revisions of this specification to add new attributes if needed, the attribute space is divided into two ranges. Attributes with type values between 0x0000 and 0x7FFF are comprehension-required attributes, which means that the STUN agent cannot successfully process the message unless it understands the attribute. Attributes with type values between 0x8000 and 0xFFFF are comprehension-optional attributes, which means that those attributes can be ignored by the STUN agent if it does not understand them.

The set of STUN attribute types is maintained by IANA. The initial set defined by this specification is found in Section 18.2.

The rest of this section describes the format of the various attributes defined in this specification.

Variants

`MappedAddress`

Fields

socket_addr: SocketAddr

Reflexive transport address of the client.

RFC5389: MAPPED-ADDRESS

The MAPPED-ADDRESS attribute indicates a reflexive transport address of the client. It consists of an 8-bit address family and a 16-bit port, followed by a fixed-length value representing the IP address. If the address family is IPv4, the address MUST be 32 bits. If the address family is IPv6, the address MUST be 128 bits. All fields must be in network byte order.

This attribute is used only by servers for achieving backwards compatibility with RFC3489 clients.

`XorMappedAddress`

Fields

socket_addr: SocketAddr

Reflexive transport address of the client.

RFC5389: XOR-MAPPED-ADDRESS

The XOR-MAPPED-ADDRESS attribute is identical to the MAPPED-ADDRESS attribute, except that the reflexive transport address is obfuscated through the XOR function.

Note: XOR-MAPPED-ADDRESS and MAPPED-ADDRESS differ only in their encoding of the transport address. The former encodes the transport address by exclusive-or’ing it with the magic cookie. The latter encodes it directly in binary. RFC 3489 originally specified only MAPPED-ADDRESS. However, deployment experience found that some NATs rewrite the 32-bit binary payloads containing the NAT’s public IP address, such as STUN’s MAPPED-ADDRESS attribute, in the well-meaning but misguided attempt at providing a generic ALG function. Such behavior interferes with the operation of STUN and also causes failure of STUN’s message-integrity checking.

`Username`

Fields

value: String

The username and password combination used in the message-integrity check.

RFC5389: USERNAME

The USERNAME attribute is used for message integrity. It identifies the username and password combination used in the message-integrity check.

The value of USERNAME is a variable-length value. It MUST contain a UTF-8 RFC3629 encoded sequence of less than 513 bytes, and MUST have been processed using SASLprep RFC4013.

`MessageIntegrity`

Fields

key: Vec<u8>

HMAC-SHA1 (RFC2104) of the STUN message.

RFC5389: MESSAGE-INTEGRITY

The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 RFC2104 of the STUN message. The MESSAGE-INTEGRITY attribute can be present in any STUN message type. Since it uses the SHA1 hash, the HMAC will be 20 bytes. The text used as input to HMAC is the STUN message, including the header, up to and including the attribute preceding the MESSAGE-INTEGRITY attribute. With the exception of the FINGERPRINT attribute, which appears after MESSAGE-INTEGRITY, agents MUST ignore all other attributes that follow MESSAGE-INTEGRITY.

The key for the HMAC depends on whether long-term or short-term credentials are in use. For long-term credentials, the key is 16 bytes:

          key = MD5(username ":" realm ":" SASLprep(password))

That is, the 16-byte key is formed by taking the MD5 hash of the result of concatenating the following five fields: (1) the username, with any quotes and trailing nulls removed, as taken from the USERNAME attribute (in which case SASLprep has already been applied); (2) a single colon; (3) the realm, with any quotes and trailing nulls removed; (4) a single colon; and (5) the password, with any trailing nulls removed and after processing using SASLprep. For example, if the username was ‘user’, the realm was ‘realm’, and the password was ‘pass’, then the 16-byte HMAC key would be the result of performing an MD5 hash on the string ‘user:realm:pass’, the resulting hash being 0x8493fbc53ba582fb4c044c456bdc40eb.

For short-term credentials:

                  key = SASLprep(password)

where MD5 is defined in RFC 1321 and SASLprep() is defined in RFC 4013.

The structure of the key when used with long-term credentials facilitates deployment in systems that also utilize SIP. Typically, SIP systems utilizing SIP’s digest authentication mechanism do not actually store the password in the database. Rather, they store a value called H(A1), which is equal to the key defined above.

Based on the rules above, the hash used to construct MESSAGE- INTEGRITY includes the length field from the STUN message header. Prior to performing the hash, the MESSAGE-INTEGRITY attribute MUST be inserted into the message (with dummy content). The length MUST then be set to point to the length of the message up to, and including, the MESSAGE-INTEGRITY attribute itself, but excluding any attributes after it. Once the computation is performed, the value of the MESSAGE-INTEGRITY attribute can be filled in, and the value of the length in the STUN header can be set to its correct value – the length of the entire message. Similarly, when validating the MESSAGE-INTEGRITY, the length field should be adjusted to point to the end of the MESSAGE-INTEGRITY attribute prior to calculating the HMAC. Such adjustment is necessary when attributes, such as FINGERPRINT, appear after MESSAGE-INTEGRITY.

`Fingerprint`

Fields

value: u32

CRC-32 of the STUN message up to (but excluding) the FINGERPRINT attribute itself, XOR’ed with the 32-bit value 0x5354554e

RFC5389: FINGERPRINT

The FINGERPRINT attribute MAY be present in all STUN messages. The value of the attribute is computed as the CRC-32 of the STUN message up to (but excluding) the FINGERPRINT attribute itself, XOR’ed with the 32-bit value 0x5354554e (the XOR helps in cases where an application packet is also using CRC-32 in it). The 32-bit CRC is the one defined in ITU V.42, which has a generator polynomial of x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1. When present, the FINGERPRINT attribute MUST be the last attribute in the message, and thus will appear after MESSAGE-INTEGRITY.

The FINGERPRINT attribute can aid in distinguishing STUN packets from packets of other protocols. See Section 8.

As with MESSAGE-INTEGRITY, the CRC used in the FINGERPRINT attribute covers the length field from the STUN message header. Therefore, this value must be correct and include the CRC attribute as part of the message length, prior to computation of the CRC. When using the FINGERPRINT attribute in a message, the attribute is first placed into the message with a dummy value, then the CRC is computed, and then the value of the attribute is updated. If the MESSAGE-INTEGRITY attribute is also present, then it must be present with the correct message-integrity value before the CRC is computed, since the CRC is done over the value of the MESSAGE-INTEGRITY attribute as well.

`ErrorCode`

Fields

class: u8

Error class

number: u8

Error number

reason: String

Reason phrase

RFC5389: ERROR-CODE

The ERROR-CODE attribute is used in error response messages. It contains a numeric error code value in the range of 300 to 699 plus a textual reason phrase encoded in UTF-8 RFC3629, and is consistent in its code assignments and semantics with SIP RFC3261 and HTTP RFC2616. The reason phrase is meant for user consumption, 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 RFC3629 encoded sequence of less than 128 characters (which can be as long as 763 bytes).

`Realm`

Fields

value: String

Text that meets the grammar for “realm-value” as described in RFC 3261 but without the double quotes and their surrounding whitespace.

RFC5389: REALM

The REALM attribute may be present in requests and responses. It contains text that meets the grammar for “realm-value” as described in RFC3261 but without the double quotes and their surrounding whitespace. That is, it is an unquoted realm-value (and is therefore a sequence of qdtext or quoted-pair). It MUST be a UTF-8 RFC3629 encoded sequence of less than 128 characters (which can be as long as 763 bytes), and MUST have been processed using SASLprep RFC 4013.

Presence of the REALM attribute in a request indicates that long-term credentials are being used for authentication. Presence in certain error responses indicates that the server wishes the client to use a long-term credential for authentication.

`Nonce`

Fields

value: String

Sequence of qdtext or quoted-pair, which are defined in RFC 3261.

RFC5389: NONCE The NONCE attribute may be present in requests and responses. It contains a sequence of qdtext or quoted-pair, which are defined in RFC3261. Note that this means that the NONCE attribute will not contain actual quote characters. See RFC2617, Section 4.3, for guidance on selection of nonce values in a server.

It MUST be less than 128 characters (which can be as long as 763 bytes).

`UnknownAttributes`

Fields

types: Vec<u16>

List of 16-bit values, each of which represents an attribute type that was not understood by the server.

RFC5389: UNKNOWN-ATTRIBUTES

The UNKNOWN-ATTRIBUTES attribute is present only in an error response when the response code in the ERROR-CODE attribute is 420.

The attribute contains a list of 16-bit values, each of which represents an attribute type that was not understood by the server.

`Software`

Fields

description: String

Textual description of the software being used by the agent sending the message.

RFC5389: SOFTWARE The SOFTWARE attribute contains a textual description of the software being used by the agent sending the message. It is used by clients and servers. Its value SHOULD include manufacturer and version number. The attribute has no impact on operation of the protocol, and serves only as a tool for diagnostic and debugging purposes. The value of SOFTWARE is variable length. It MUST be a UTF-8 RFC3629 encoded sequence of less than 128 characters (which can be as long as 763 bytes).

`AlternateServer`

Fields

socket_addr: SocketAddr

Alternate transport address identifying a different STUN server that the STUN client should try.

RFC5389: ALTERNATE-SERVER

The alternate server represents an alternate transport address identifying a different STUN server that the STUN client should try.

It is encoded in the same way as MAPPED-ADDRESS, and thus refers to a single server by IP address. The IP address family MUST be identical to that of the source IP address of the request.

`Priority`

Fields

value: u32

Value computed by the algorithm in Section 5.1.2 of RFC8445 for the local candidate, but with the candidate type preference of peer-reflexive candidates.

RFC8445: PRIORITY

The PRIORITY attribute MUST be included in a Binding request and be set to the value computed by the algorithm in Section 5.1.2 for the local candidate, but with the candidate type preference of peer- reflexive candidates.

`UseCandidate`

RFC8445: USE-CANDIDATE

The controlling agent MUST include the USE-CANDIDATE attribute in order to nominate a candidate pair (Section 8.1.1). The controlled agent MUST NOT include the USE-CANDIDATE attribute in a Binding request.