STUN
Overview
Session Traversal Utilities for NAT (STUN, RFC 8489) is a protocol that lets a device learn which address and port it has on the outside of a NAT: it sends a Binding request to a server, and the server answers with the address the request came from. Interactive Connectivity Establishment (ICE, RFC 8445) and TURN (RFC 8656) use the same messages.
The base of the STUN library is a message codec. It parses received messages and builds messages to send, with the attributes that ICE adds, and it computes and verifies the MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and FINGERPRINT attributes. The codec does no I/O and keeps no state: every function works on buffers of the caller. An application that uses the codec alone owns the socket, generates the transaction ids and retransmits its requests.
The library comes in layers. The codec is usable alone; the Binding transaction and the socket client are enabled together:
Layer |
Kconfig option |
What it does |
|---|---|---|
Message codec |
Parses and builds messages, with the attributes of ICE, and computes MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and FINGERPRINT. |
|
Binding transaction |
One Binding request, its retransmissions and the response. No I/O and no clock either: the caller sends what it is told to send, feeds in what it receives and says what time it is. |
|
Socket client |
Blocking calls that run a transaction over a UDP socket and return the address the server saw. |
An application that only wants to know its public address uses the socket client. A protocol that shares its socket with STUN, as ICE does, uses the transaction and the codec and does the I/O itself.
Note
This library is marked experimental. The API and the Kconfig options may change between releases.
Configuration
Enable the library with CONFIG_STUN; it selects what it
needs, so that a minimal prj.conf is:
CONFIG_NETWORKING=y
CONFIG_STUN=y
- Message integrity
CONFIG_PSA_WANT_ALG_HMAC,CONFIG_PSA_WANT_KEY_TYPE_HMAC,CONFIG_PSA_WANT_ALG_SHA_1(MESSAGE-INTEGRITY) andCONFIG_PSA_WANT_ALG_SHA_256(MESSAGE-INTEGRITY-SHA256), all on by default. The library initializes the PSA Crypto API itself.- Address families
CONFIG_NET_IPV6for IPv6 addresses. Without it the address functions return-EAFNOSUPPORTfor such an address, and the message still parses.- Binding transaction and socket client
CONFIG_STUN_CLIENT, which needsCONFIG_NET_SOCKETSandCONFIG_NET_UDP. The transaction id of a request has to be unpredictable, so the client depends on a cryptographically secure random number generator. A server given by host name needsCONFIG_DNS_RESOLVER; a literal address does not.CONFIG_STUN_CLIENT_SOFTWAREis what the requests carry in SOFTWARE.- Retransmission schedule
The parameters of RFC 8489 section 6.2.1 for every Binding transaction of the build:
CONFIG_STUN_BINDING_RTO_MS, the initial retransmission timeout (500 ms by default, 500 to 60000),CONFIG_STUN_BINDING_MAX_TRANSMITS, Rc, the number of times the request is sent (7 by default, 1 to 16), andCONFIG_STUN_BINDING_FINAL_WAIT_RTO, Rm, the wait after the last transmission in initial timeouts (16 by default, 1 to 255).- Logging
CONFIG_STUN_LOG_LEVEL_DBGand its siblings, available underCONFIG_NET_LOG. Why a received message was refused is logged at the debug level only, so that traffic from the network cannot fill the log. Errors are logged for failures of the PSA Crypto backend and of the random number generator the client takes its transaction ids from. Keys and integrity values are never logged.
Usage
Finding out the public address
stun_client_simple() resolves the server, opens a UDP socket, connects
it to the server, so that the socket receives only the datagrams of the server,
asks, and closes the socket:
#include <zephyr/net/stun_client.h>
struct net_sockaddr_storage mapped;
int rc;
/* Port 0 is the default port of STUN, 3478; wait 5 seconds at most. */
rc = stun_client_simple("stun.example.org", 0, 5000, &mapped);
if (rc == 0) {
/* mapped is the address the server saw the request come from */
}
A name that resolves to several addresses, an IPv4 and an IPv6 one for example, is asked at one address after another until one of them answers. The time is for the whole call: each address gets an equal part of what is left of it, so an address that fails at once leaves its part to the others. With no time given, 0, each address is asked for as long as the retransmission schedule lasts.
The address tells the public IP address of the device. The port belongs to the
socket of that one request, which is closed by the time the call returns. To
learn the address and port that peers can reach a socket of the application at,
ask from that very socket with stun_client_query():
rc = stun_client_query(sock, &server, sizeof(struct net_sockaddr_in), 5000,
&mapped);
For the duration of the call the socket belongs to the transaction: datagrams that are not the answer of the server are received and dropped.
The request is retransmitted as RFC 8489 section 6.2.1 has it: with the default configuration after 0.5, 1.5, 3.5 seconds and so on, for 39.5 seconds in all unless the caller sets a shorter time.
The STUN client sample shows the client in an application.
Receiving a message
stun_has_valid_header() tells a STUN message from the other protocols
that may share its port, such as DTLS and RTP (RFC 7983).
stun_parse() then checks the whole message and fills a
stun_msg with the header fields and the attributes the codec
understands. The structure refers to the buffer that was parsed, which has to
stay unchanged while the structure is in use: the functions that take the
structure read the message from it. Finish with the structure before the buffer
receives the next datagram or a response is built in it.
A received message is processed in the order of RFC 8489 section 6.3:
stun_parse()refuses a malformed message. Its description lists the rules the parser applies.stun_verify_fingerprint()checks FINGERPRINT, if the STUN usage requires the attribute.stun_verify_integrity()orstun_verify_integrity_sha256()authenticates the message, if the STUN usage protects it. The parser cannot do it, because it has no key.stun_unknown_attrs()reports the attributes the receiver is required to understand and does not.
An attribute of another STUN usage is read with stun_find_attr(). An
attribute in the XOR-MAPPED-ADDRESS format, such as XOR-PEER-ADDRESS of TURN, is
decoded with stun_get_xor_address(). One in the MAPPED-ADDRESS format,
such as ALTERNATE-SERVER, is decoded by the application from the value
stun_find_attr() returns: the XOR function would decode it without
complaint and get the address wrong.
Building a message
A message is built in a buffer of the caller with a stun_builder.
The attributes are added in the order of the calls, and the closing attributes
come last: MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256, then FINGERPRINT. This
is the Binding request of an ICE connectivity check (RFC 8445 section 7.2.4):
#include <zephyr/net/stun.h>
#include <zephyr/random/random.h>
struct stun_builder b;
uint8_t txid[STUN_TXID_SIZE];
uint8_t out[128];
int len;
/* The transaction id of a request has to be unpredictable. */
if (sys_csrand_get(txid, sizeof(txid)) != 0) {
return;
}
if (stun_builder_init(&b, out, sizeof(out), STUN_BINDING_REQUEST, txid) != 0 ||
stun_add_username(&b, username) != 0 ||
stun_add_priority(&b, priority) != 0 ||
stun_add_ice_controlling(&b, tiebreaker) != 0) {
return;
}
/* MESSAGE-INTEGRITY with the password of the peer, then FINGERPRINT. */
len = stun_finish(&b, key, key_len);
if (len > 0) {
send_datagram(out, len);
}
The example checks every return value, because the builder remembers only some
of the failures: stun_builder tells which. stun_finish()
signs with MESSAGE-INTEGRITY alone. A message with no integrity attribute, with
MESSAGE-INTEGRITY-SHA256 or with both is closed with stun_finish_plain()
instead, as in the next example.
Answering a request
This is how an agent answers a Binding request that is protected with a
short-term credential (RFC 8489 section 9.1.3). USERNAME names the
credential; the key of the integrity check is its password, processed with the
OpaqueString profile (RFC 8265) as RFC 8489 section 9.1.1 requires. The
example’s lookup_password() stands for the credential store of the
application and returns the password in that form. The request is authenticated
with MESSAGE-INTEGRITY-SHA256 if it carries that attribute and with
MESSAGE-INTEGRITY otherwise, and the response is protected the same way the
request was:
struct stun_builder b;
struct stun_msg msg;
const uint8_t *key;
size_t key_len;
uint8_t out[128];
int len;
if (!stun_has_valid_header(buf, n) || stun_parse(buf, n, &msg) != 0) {
return;
}
if (msg.type != STUN_BINDING_REQUEST) {
return;
}
/* No USERNAME is a 400, a name the agent does not know is a 401. */
if (msg.username == NULL ||
lookup_password(msg.username, msg.username_len, &key, &key_len) != 0) {
return;
}
if (msg.has_integrity_sha256) {
if (stun_verify_integrity_sha256(&msg, key, key_len,
STUN_INTEGRITY_SHA256_MAX_LEN) != 0) {
return;
}
} else if (stun_verify_integrity(&msg, key, key_len) != 0) {
return;
}
/* Unknown attributes are looked at after the authentication. */
if (stun_unknown_attrs(&msg, NULL, 0, NULL, 0) != 0) {
return;
}
if (stun_builder_init(&b, out, sizeof(out), STUN_BINDING_SUCCESS_RESPONSE,
msg.txid) != 0 ||
stun_add_xor_mapped_address(&b, from) != 0) {
return;
}
if (msg.has_integrity_sha256) {
if (stun_add_integrity_sha256(&b, key, key_len) != 0) {
return;
}
len = stun_finish_plain(&b);
} else {
len = stun_finish(&b, key, key_len);
}
if (len > 0) {
send_datagram(out, len);
}
The example drops a request it cannot process. A server that answers strangers
sends an error response instead: 400 (Bad Request) if USERNAME or the integrity
attribute is missing, 401 (Unauthenticated) if the name is unknown or the HMAC
does not match, and 420 (Unknown Attribute) with UNKNOWN-ATTRIBUTES if
stun_unknown_attrs() reported any. The checks run in this order, so that
a request which fails more than one of them gets the first of these codes. The
codec builds the responses with stun_add_error_code() and
stun_add_unknown_attributes().
Limitations
The following is not part of the library:
Transactions other than a Binding request without credentials. The transaction builds its request with SOFTWARE and FINGERPRINT only; a request that carries USERNAME and MESSAGE-INTEGRITY, such as an ICE connectivity check, is built with the codec and retransmitted by the application.
Retransmission parameters of a single transaction. The initial timeout, Rc and Rm are set with Kconfig options only, for all the transactions of the build; a transaction cannot be started with its own, and the timeout is neither measured nor remembered per server.
ICE and TURN. The codec has the attributes of ICE;
stun_add_attr()andstun_find_attr()carry those of other STUN usages as raw values, andstun_add_xor_address()andstun_get_xor_address()the ones in the XOR-MAPPED-ADDRESS format.The long-term credential mechanism. The parser limits the length of REALM and NONCE; the key derivation, USERHASH and PASSWORD-ALGORITHM are left to the application.
The OpaqueString profile (RFC 8265), which USERNAME and the password of a short-term credential have to be processed with before they are given to the library. ICE credentials are ASCII and need no processing.
The framing of STUN over TCP and TLS.
Testing
The tests under tests/net/lib/stun/ check the codec against the sample messages of RFC 5769 and of RFC 8489 Appendix B.1, and the Binding transaction against the retransmission schedule of RFC 8489 section 6.2.1. The tests under tests/net/lib/stun_client/ run the socket client against a server on the loopback interface.