Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
STUN (Session Traversal Utilities for NAT)

Message codec for STUN (RFC 8489) with the attributes of ICE (RFC 8445). More...

Files

file  stun.h
 STUN (Session Traversal Utilities for NAT, RFC 8489) message codec.

Data Structures

struct  stun_msg
 A parsed message. More...
struct  stun_builder
 A message under construction. More...

Macros

#define STUN_MAGIC_COOKIE   0x2112A442UL
 Magic cookie, the second 32-bit word of every message (RFC 8489, section-5).
#define STUN_HEADER_SIZE   20U
 Size of the message header.
#define STUN_TXID_SIZE   12U
 Size of the transaction id.
#define STUN_INTEGRITY_LEN   20U
 Length of the MESSAGE-INTEGRITY value, an HMAC-SHA1.
#define STUN_INTEGRITY_SHA256_MIN_LEN   16U
 Shortest MESSAGE-INTEGRITY-SHA256 value a STUN Usage may allow (RFC 8489, section-14.6).
#define STUN_INTEGRITY_SHA256_MAX_LEN   32U
 Length of a MESSAGE-INTEGRITY-SHA256 value that is not truncated.
#define STUN_TEXT_MAX_LEN   763U
 Longest USERNAME, SOFTWARE, REALM, NONCE or ERROR-CODE reason phrase the parser accepts, in bytes (RFC 8489, section-14.3, RFC 8489, section-14.8).
#define STUN_USERNAME_MAX_LEN   508U
 Longest USERNAME the builder sends, in bytes (RFC 8489, section-14.3).
#define STUN_TEXT_MAX_CHARS   127U
 Longest SOFTWARE and ERROR-CODE reason phrase the builder sends, in UTF-8 characters (RFC 8489, section-14.8, RFC 8489, section-14.14).
#define STUN_METHOD_BINDING   0x001U
 Binding method (RFC 8489, section-18.2).

Enumerations

enum  stun_class { STUN_CLASS_REQUEST = 0 , STUN_CLASS_INDICATION = 1 , STUN_CLASS_SUCCESS = 2 , STUN_CLASS_ERROR = 3 }
 Message classes (RFC 8489, section-5). More...

Functions

bool stun_has_valid_header (const uint8_t *buf, size_t len)
 Check that a datagram starts with a valid STUN header.
int stun_parse (const uint8_t *buf, size_t len, struct stun_msg *out)
 Parse one datagram.
uint16_t stun_msg_type_compose (uint16_t method, enum stun_class msg_class)
 Compose a message type.
uint16_t stun_msg_type_get_method (uint16_t type)
 Get the method of a message type.
enum stun_class stun_msg_type_get_class (uint16_t type)
 Get the class of a message type.
int stun_find_attr (const struct stun_msg *msg, uint16_t attr_type, const uint8_t **value, uint16_t *value_len)
 Find an attribute by type.
int stun_unknown_attrs (const struct stun_msg *msg, const uint16_t *known, size_t n_known, uint16_t *out, size_t cap)
 List the comprehension-required attributes nobody understands.
int stun_verify_integrity (const struct stun_msg *msg, const uint8_t *key, size_t key_len)
 Verify MESSAGE-INTEGRITY.
int stun_verify_integrity_sha256 (const struct stun_msg *msg, const uint8_t *key, size_t key_len, size_t min_len)
 Verify MESSAGE-INTEGRITY-SHA256.
int stun_verify_fingerprint (const struct stun_msg *msg)
 Verify FINGERPRINT.
int stun_get_xor_address (const struct stun_msg *msg, uint16_t attr_type, struct net_sockaddr *addr)
 Decode an attribute in the XOR-MAPPED-ADDRESS format.
int stun_get_xor_mapped_address (const struct stun_msg *msg, struct net_sockaddr *addr)
 Decode XOR-MAPPED-ADDRESS.
int stun_builder_init (struct stun_builder *builder, uint8_t *buf, size_t buf_size, uint16_t msg_type, const uint8_t transaction_id[12U])
 Start a message.
int stun_add_attr (struct stun_builder *builder, uint16_t attr_type, const uint8_t *value, size_t value_len)
 Add an attribute by type and value.
int stun_add_software (struct stun_builder *builder, const char *sw)
 Add SOFTWARE.
int stun_add_username (struct stun_builder *builder, const char *username)
 Add USERNAME.
int stun_add_xor_address (struct stun_builder *builder, uint16_t attr_type, const struct net_sockaddr *addr)
 Add an attribute in the XOR-MAPPED-ADDRESS format.
int stun_add_xor_mapped_address (struct stun_builder *builder, const struct net_sockaddr *addr)
 Add XOR-MAPPED-ADDRESS.
int stun_add_priority (struct stun_builder *builder, uint32_t priority)
 Add PRIORITY.
int stun_add_use_candidate (struct stun_builder *builder)
 Add USE-CANDIDATE.
int stun_add_error_code (struct stun_builder *builder, uint16_t code, const char *reason)
 Add ERROR-CODE: an error code and its reason phrase.
int stun_add_unknown_attributes (struct stun_builder *builder, const uint16_t *types, size_t n_types)
 Add UNKNOWN-ATTRIBUTES.
int stun_add_ice_controlling (struct stun_builder *builder, uint64_t tiebreaker)
 Add ICE-CONTROLLING.
int stun_add_ice_controlled (struct stun_builder *builder, uint64_t tiebreaker)
 Add ICE-CONTROLLED.
int stun_add_integrity (struct stun_builder *builder, const uint8_t *key, size_t key_len)
 Add MESSAGE-INTEGRITY.
int stun_add_integrity_sha256 (struct stun_builder *builder, const uint8_t *key, size_t key_len)
 Add MESSAGE-INTEGRITY-SHA256.
int stun_add_fingerprint (struct stun_builder *builder)
 Add FINGERPRINT.
int stun_builder_len (const struct stun_builder *builder)
 Get the length of the message built so far.
int stun_finish (struct stun_builder *builder, const uint8_t *key, size_t key_len)
 Close a message with MESSAGE-INTEGRITY and FINGERPRINT.
int stun_finish_plain (struct stun_builder *builder)
 Close a message with FINGERPRINT alone.

Message types

#define STUN_BINDING_REQUEST   0x0001U
 Binding request.
#define STUN_BINDING_SUCCESS_RESPONSE   0x0101U
 Binding success response.
#define STUN_BINDING_ERROR_RESPONSE   0x0111U
 Binding error response.

Attribute types the codec understands

RFC 8489, section-18.3 and RFC 8445, section-20.1.

#define STUN_ATTR_MAPPED_ADDRESS   0x0001U
 MAPPED-ADDRESS.
#define STUN_ATTR_USERNAME   0x0006U
 USERNAME.
#define STUN_ATTR_MESSAGE_INTEGRITY   0x0008U
 MESSAGE-INTEGRITY.
#define STUN_ATTR_ERROR_CODE   0x0009U
 ERROR-CODE.
#define STUN_ATTR_UNKNOWN_ATTRIBUTES   0x000AU
 UNKNOWN-ATTRIBUTES.
#define STUN_ATTR_REALM   0x0014U
 REALM.
#define STUN_ATTR_NONCE   0x0015U
 NONCE.
#define STUN_ATTR_MESSAGE_INTEGRITY_SHA256   0x001CU
 MESSAGE-INTEGRITY-SHA256.
#define STUN_ATTR_XOR_MAPPED_ADDRESS   0x0020U
 XOR-MAPPED-ADDRESS.
#define STUN_ATTR_PRIORITY   0x0024U
 PRIORITY (ICE).
#define STUN_ATTR_USE_CANDIDATE   0x0025U
 USE-CANDIDATE (ICE).
#define STUN_ATTR_SOFTWARE   0x8022U
 SOFTWARE.
#define STUN_ATTR_FINGERPRINT   0x8028U
 FINGERPRINT.
#define STUN_ATTR_ICE_CONTROLLED   0x8029U
 ICE-CONTROLLED (ICE).
#define STUN_ATTR_ICE_CONTROLLING   0x802AU
 ICE-CONTROLLING (ICE).

Detailed Description

Message codec for STUN (RFC 8489) with the attributes of ICE (RFC 8445).

Since
4.6
Version
0.1.0

Parsing and building of STUN messages as RFC 8489 defines them, with the attributes of ICE (RFC 8445). The library does no I/O and keeps no state: every function works on buffers of the caller. Message integrity is computed through the PSA Crypto API, which the library initialises itself.

Macro Definition Documentation

◆ STUN_ATTR_ERROR_CODE

#define STUN_ATTR_ERROR_CODE   0x0009U

#include <zephyr/net/stun.h>

ERROR-CODE.

◆ STUN_ATTR_FINGERPRINT

#define STUN_ATTR_FINGERPRINT   0x8028U

#include <zephyr/net/stun.h>

FINGERPRINT.

◆ STUN_ATTR_ICE_CONTROLLED

#define STUN_ATTR_ICE_CONTROLLED   0x8029U

#include <zephyr/net/stun.h>

ICE-CONTROLLED (ICE).

◆ STUN_ATTR_ICE_CONTROLLING

#define STUN_ATTR_ICE_CONTROLLING   0x802AU

#include <zephyr/net/stun.h>

ICE-CONTROLLING (ICE).

◆ STUN_ATTR_MAPPED_ADDRESS

#define STUN_ATTR_MAPPED_ADDRESS   0x0001U

#include <zephyr/net/stun.h>

MAPPED-ADDRESS.

◆ STUN_ATTR_MESSAGE_INTEGRITY

#define STUN_ATTR_MESSAGE_INTEGRITY   0x0008U

#include <zephyr/net/stun.h>

MESSAGE-INTEGRITY.

◆ STUN_ATTR_MESSAGE_INTEGRITY_SHA256

#define STUN_ATTR_MESSAGE_INTEGRITY_SHA256   0x001CU

#include <zephyr/net/stun.h>

MESSAGE-INTEGRITY-SHA256.

◆ STUN_ATTR_NONCE

#define STUN_ATTR_NONCE   0x0015U

#include <zephyr/net/stun.h>

NONCE.

◆ STUN_ATTR_PRIORITY

#define STUN_ATTR_PRIORITY   0x0024U

#include <zephyr/net/stun.h>

PRIORITY (ICE).

◆ STUN_ATTR_REALM

#define STUN_ATTR_REALM   0x0014U

#include <zephyr/net/stun.h>

REALM.

◆ STUN_ATTR_SOFTWARE

#define STUN_ATTR_SOFTWARE   0x8022U

#include <zephyr/net/stun.h>

SOFTWARE.

◆ STUN_ATTR_UNKNOWN_ATTRIBUTES

#define STUN_ATTR_UNKNOWN_ATTRIBUTES   0x000AU

#include <zephyr/net/stun.h>

UNKNOWN-ATTRIBUTES.

◆ STUN_ATTR_USE_CANDIDATE

#define STUN_ATTR_USE_CANDIDATE   0x0025U

#include <zephyr/net/stun.h>

USE-CANDIDATE (ICE).

◆ STUN_ATTR_USERNAME

#define STUN_ATTR_USERNAME   0x0006U

#include <zephyr/net/stun.h>

USERNAME.

◆ STUN_ATTR_XOR_MAPPED_ADDRESS

#define STUN_ATTR_XOR_MAPPED_ADDRESS   0x0020U

#include <zephyr/net/stun.h>

XOR-MAPPED-ADDRESS.

◆ STUN_BINDING_ERROR_RESPONSE

#define STUN_BINDING_ERROR_RESPONSE   0x0111U

#include <zephyr/net/stun.h>

Binding error response.

◆ STUN_BINDING_REQUEST

#define STUN_BINDING_REQUEST   0x0001U

#include <zephyr/net/stun.h>

Binding request.

◆ STUN_BINDING_SUCCESS_RESPONSE

#define STUN_BINDING_SUCCESS_RESPONSE   0x0101U

#include <zephyr/net/stun.h>

Binding success response.

◆ STUN_HEADER_SIZE

#define STUN_HEADER_SIZE   20U

#include <zephyr/net/stun.h>

Size of the message header.

◆ STUN_INTEGRITY_LEN

#define STUN_INTEGRITY_LEN   20U

#include <zephyr/net/stun.h>

Length of the MESSAGE-INTEGRITY value, an HMAC-SHA1.

◆ STUN_INTEGRITY_SHA256_MAX_LEN

#define STUN_INTEGRITY_SHA256_MAX_LEN   32U

#include <zephyr/net/stun.h>

Length of a MESSAGE-INTEGRITY-SHA256 value that is not truncated.

◆ STUN_INTEGRITY_SHA256_MIN_LEN

#define STUN_INTEGRITY_SHA256_MIN_LEN   16U

#include <zephyr/net/stun.h>

Shortest MESSAGE-INTEGRITY-SHA256 value a STUN Usage may allow (RFC 8489, section-14.6).

◆ STUN_MAGIC_COOKIE

#define STUN_MAGIC_COOKIE   0x2112A442UL

#include <zephyr/net/stun.h>

Magic cookie, the second 32-bit word of every message (RFC 8489, section-5).

◆ STUN_METHOD_BINDING

#define STUN_METHOD_BINDING   0x001U

#include <zephyr/net/stun.h>

Binding method (RFC 8489, section-18.2).

◆ STUN_TEXT_MAX_CHARS

#define STUN_TEXT_MAX_CHARS   127U

#include <zephyr/net/stun.h>

Longest SOFTWARE and ERROR-CODE reason phrase the builder sends, in UTF-8 characters (RFC 8489, section-14.8, RFC 8489, section-14.14).

◆ STUN_TEXT_MAX_LEN

#define STUN_TEXT_MAX_LEN   763U

#include <zephyr/net/stun.h>

Longest USERNAME, SOFTWARE, REALM, NONCE or ERROR-CODE reason phrase the parser accepts, in bytes (RFC 8489, section-14.3, RFC 8489, section-14.8).

◆ STUN_TXID_SIZE

#define STUN_TXID_SIZE   12U

#include <zephyr/net/stun.h>

Size of the transaction id.

◆ STUN_USERNAME_MAX_LEN

#define STUN_USERNAME_MAX_LEN   508U

#include <zephyr/net/stun.h>

Longest USERNAME the builder sends, in bytes (RFC 8489, section-14.3).

Enumeration Type Documentation

◆ stun_class

enum stun_class

#include <zephyr/net/stun.h>

Message classes (RFC 8489, section-5).

Enumerator
STUN_CLASS_REQUEST 

Request.

STUN_CLASS_INDICATION 

Indication.

STUN_CLASS_SUCCESS 

Success response.

STUN_CLASS_ERROR 

Error response.

Function Documentation

◆ stun_add_attr()

int stun_add_attr ( struct stun_builder * builder,
uint16_t attr_type,
const uint8_t * value,
size_t value_len )

#include <zephyr/net/stun.h>

Add an attribute by type and value.

For the attributes of STUN extensions. MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and FINGERPRINT have functions of their own and are refused here.

Parameters
[in,out]builderBuilder.
attr_typeAttribute type.
valueValue; may be NULL if value_len is 0.
value_lenIts length, at most 65535.
Return values
0Success.
-EINVALbuilder is NULL, value_len is over 65535, value is NULL while value_len is not 0, or attr_type is one of the closing attributes.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_error_code()

int stun_add_error_code ( struct stun_builder * builder,
uint16_t code,
const char * reason )

#include <zephyr/net/stun.h>

Add ERROR-CODE: an error code and its reason phrase.

Parameters
[in,out]builderBuilder.
codeError code, 300 to 699.
reasonReason phrase, at most STUN_TEXT_MAX_CHARS UTF-8 characters; NULL for none.
Return values
0Success.
-EINVALbuilder is NULL, code is outside 300 to 699, or reason is not well-formed UTF-8 (RFC 3629, section-4) or is longer than STUN_TEXT_MAX_CHARS characters.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_fingerprint()

int stun_add_fingerprint ( struct stun_builder * builder)

#include <zephyr/net/stun.h>

Add FINGERPRINT.

The last attribute of a message (RFC 8489, section-14.7): nothing can be added after it.

Parameters
[in,out]builderBuilder.
Return values
0Success.
-EINVALbuilder is NULL.
-EPERMFINGERPRINT has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_ice_controlled()

int stun_add_ice_controlled ( struct stun_builder * builder,
uint64_t tiebreaker )

#include <zephyr/net/stun.h>

Add ICE-CONTROLLED.

Parameters
[in,out]builderBuilder.
tiebreakerTie-breaker of the agent (RFC 8445, section-7.1.3).
Return values
0Success.
-EINVALbuilder is NULL.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_ice_controlling()

int stun_add_ice_controlling ( struct stun_builder * builder,
uint64_t tiebreaker )

#include <zephyr/net/stun.h>

Add ICE-CONTROLLING.

Parameters
[in,out]builderBuilder.
tiebreakerTie-breaker of the agent (RFC 8445, section-7.1.3).
Return values
0Success.
-EINVALbuilder is NULL.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_integrity()

int stun_add_integrity ( struct stun_builder * builder,
const uint8_t * key,
size_t key_len )

#include <zephyr/net/stun.h>

Add MESSAGE-INTEGRITY.

Signs what the message holds so far with HMAC-SHA1 (RFC 8489, section-14.5). After it only MESSAGE-INTEGRITY-SHA256 and FINGERPRINT can be added.

Parameters
[in,out]builderBuilder.
keyKey. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing.
key_lenIts length, not 0.
Return values
0Success.
-EINVALbuilder or key is NULL, or key_len is 0.
-EPERMMESSAGE-INTEGRITY or a later closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOThe PSA backend failed to compute the HMAC, now or in an earlier call.

◆ stun_add_integrity_sha256()

int stun_add_integrity_sha256 ( struct stun_builder * builder,
const uint8_t * key,
size_t key_len )

#include <zephyr/net/stun.h>

Add MESSAGE-INTEGRITY-SHA256.

Signs what the message holds so far with HMAC-SHA256, not truncated (RFC 8489, section-14.6). After it only FINGERPRINT can be added. RFC 8489, section-9.1.2: a request or an indication carries both integrity attributes unless the two agents know by other means which one they share, as ICE agents do.

Parameters
[in,out]builderBuilder.
keyKey. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing.
key_lenIts length, not 0.
Return values
0Success.
-EINVALbuilder or key is NULL, or key_len is 0.
-EPERMMESSAGE-INTEGRITY-SHA256 or FINGERPRINT has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOThe PSA backend failed to compute the HMAC, now or in an earlier call.

◆ stun_add_priority()

int stun_add_priority ( struct stun_builder * builder,
uint32_t priority )

#include <zephyr/net/stun.h>

Add PRIORITY.

Parameters
[in,out]builderBuilder.
priorityPriority of the candidate (RFC 8445, section-7.1.1).
Return values
0Success.
-EINVALbuilder is NULL.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_software()

int stun_add_software ( struct stun_builder * builder,
const char * sw )

#include <zephyr/net/stun.h>

Add SOFTWARE.

Parameters
[in,out]builderBuilder.
swDescription of the software, at most STUN_TEXT_MAX_CHARS UTF-8 characters.
Return values
0Success.
-EINVALbuilder or sw is NULL, or sw is not well-formed UTF-8 (RFC 3629, section-4) or is longer than STUN_TEXT_MAX_CHARS characters.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_unknown_attributes()

int stun_add_unknown_attributes ( struct stun_builder * builder,
const uint16_t * types,
size_t n_types )

#include <zephyr/net/stun.h>

Add UNKNOWN-ATTRIBUTES.

The attribute a 420 error response carries (RFC 8489, section-6.3.1); the list is what stun_unknown_attrs() returned for the request.

Parameters
[in,out]builderBuilder.
typesAttribute types; may be NULL if n_types is 0.
n_typesNumber of types.
Return values
0Success.
-EINVALbuilder is NULL, types is NULL while n_types is not 0, or n_types is over 32767.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_use_candidate()

int stun_add_use_candidate ( struct stun_builder * builder)

#include <zephyr/net/stun.h>

Add USE-CANDIDATE.

Parameters
[in,out]builderBuilder.
Return values
0Success.
-EINVALbuilder is NULL.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_username()

int stun_add_username ( struct stun_builder * builder,
const char * username )

#include <zephyr/net/stun.h>

Add USERNAME.

Parameters
[in,out]builderBuilder.
usernameUser name, at most STUN_USERNAME_MAX_LEN bytes, already processed with the OpaqueString profile (RFC 8265).
Return values
0Success.
-EINVALbuilder or username is NULL, or username is not well-formed UTF-8 (RFC 3629, section-4) or is longer than STUN_USERNAME_MAX_LEN bytes.
-EPERMA closing attribute has been added already.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_xor_address()

int stun_add_xor_address ( struct stun_builder * builder,
uint16_t attr_type,
const struct net_sockaddr * addr )

#include <zephyr/net/stun.h>

Add an attribute in the XOR-MAPPED-ADDRESS format.

Parameters
[in,out]builderBuilder.
attr_typeAttribute type.
addrIPv4 or IPv6 address and port.
Return values
0Success.
-EINVALbuilder or addr is NULL, or attr_type is one of the closing attributes.
-EPERMA closing attribute has been added already.
-EAFNOSUPPORTThe family of addr is neither IPv4 nor IPv6, or it is IPv6 and CONFIG_NET_IPV6 is not enabled.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_add_xor_mapped_address()

int stun_add_xor_mapped_address ( struct stun_builder * builder,
const struct net_sockaddr * addr )

#include <zephyr/net/stun.h>

Add XOR-MAPPED-ADDRESS.

Parameters
[in,out]builderBuilder.
addrIPv4 or IPv6 address and port.
Return values
0Success.
-EINVALbuilder or addr is NULL.
-EPERMA closing attribute has been added already.
-EAFNOSUPPORTThe family of addr is neither IPv4 nor IPv6, or it is IPv6 and CONFIG_NET_IPV6 is not enabled.
-EMSGSIZEThe attribute does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_builder_init()

int stun_builder_init ( struct stun_builder * builder,
uint8_t * buf,
size_t buf_size,
uint16_t msg_type,
const uint8_t transaction_id[12U] )

#include <zephyr/net/stun.h>

Start a message.

Writes the message header into buf. An error is returned and remembered in the builder: every later call on it returns the same error.

Parameters
[out]builderBuilder.
[out]bufBuffer for the message.
buf_sizeIts size, at least STUN_HEADER_SIZE.
msg_typeMessage type, 14 bits: the two top bits are zero (RFC 8489, section-5).
transaction_idTransaction id. For a request it has to come from a cryptographically secure random generator (RFC 8489, section-5).
Return values
0Success.
-EINVALbuilder, buf or transaction_id is NULL, or msg_type has one of its two top bits set.
-EMSGSIZEbuf_size is below STUN_HEADER_SIZE.

◆ stun_builder_len()

int stun_builder_len ( const struct stun_builder * builder)

#include <zephyr/net/stun.h>

Get the length of the message built so far.

Parameters
builderBuilder.
Returns
The length of the message in bytes, if no call has failed.
Return values
-EINVALbuilder is NULL.
-EMSGSIZEAn earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_find_attr()

int stun_find_attr ( const struct stun_msg * msg,
uint16_t attr_type,
const uint8_t ** value,
uint16_t * value_len )

#include <zephyr/net/stun.h>

Find an attribute by type.

Returns the first attribute of the type that stands ahead of the integrity boundary (see stun_parse()): later occurrences, and anything after the boundary, are ignored as the parser ignores them. MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and FINGERPRINT are found where the parser recorded them. Meant for the attributes stun_msg does not carry; the value of a type the codec does not know is not checked, only that it lies inside the message.

Parameters
msgResult of stun_parse().
attr_typeAttribute type.
[out]valueReceives a pointer to the value, inside the parsed buffer; written only on success.
[out]value_lenReceives the length of the value, without padding; written only on success.
Return values
0Success.
-ENOENTNo attribute of the type ahead of the integrity boundary.
-EINVALNULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse().

◆ stun_finish()

int stun_finish ( struct stun_builder * builder,
const uint8_t * key,
size_t key_len )

#include <zephyr/net/stun.h>

Close a message with MESSAGE-INTEGRITY and FINGERPRINT.

Signs the message with HMAC-SHA1 over key, adds FINGERPRINT and returns the length of the finished message, ready to be sent; nothing can be added to it afterwards. The same as stun_add_integrity() followed by stun_finish_plain(). This is what an ICE agent ends its connectivity checks and their responses with: a check must be signed with the short-term credential (RFC 8445, section-7.2.2) and carry FINGERPRINT (RFC 8445, section-7.2.4), and so must the response (RFC 8445, section-7.3).

The key is required. A message that is not to be signed is closed with stun_finish_plain() instead. The two are kept apart, rather than one function taking a NULL key for "no signature", so that a missing key fails here with -EINVAL instead of quietly producing a message without MESSAGE-INTEGRITY, which a peer that expects one would discard.

Parameters
[in,out]builderBuilder.
keyKey. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing.
key_lenIts length, not 0.
Returns
The length of the message in bytes.
Return values
-EINVALbuilder or key is NULL, or key_len is 0.
-EPERMMESSAGE-INTEGRITY or a later closing attribute has been added already.
-EMSGSIZEThe closing attributes do not fit, or an earlier call ran out of room.
-EIOThe PSA backend failed to compute the HMAC, now or in an earlier call.

◆ stun_finish_plain()

int stun_finish_plain ( struct stun_builder * builder)

#include <zephyr/net/stun.h>

Close a message with FINGERPRINT alone.

Adds FINGERPRINT and returns the length of the finished message, ready to be sent; nothing can be added to it afterwards. The same as stun_add_fingerprint() followed by stun_builder_len().

For a message that carries no integrity attribute, such as a Binding request to a public STUN server, which has no credential to check. It also closes a message the caller has signed itself, for example with both stun_add_integrity() and stun_add_integrity_sha256() as RFC 8489, section-9.1.2 asks of a request or an indication when the agents do not know which algorithm they share; stun_finish() adds MESSAGE-INTEGRITY alone.

Unlike stun_finish() it takes no key, so choosing it is choosing not to sign here; see stun_finish() for why the two are separate.

Parameters
[in,out]builderBuilder.
Returns
The length of the message in bytes.
Return values
-EINVALbuilder is NULL.
-EPERMFINGERPRINT has been added already.
-EMSGSIZEFINGERPRINT does not fit, or an earlier call ran out of room.
-EIOAn earlier HMAC failed in the PSA backend.

◆ stun_get_xor_address()

int stun_get_xor_address ( const struct stun_msg * msg,
uint16_t attr_type,
struct net_sockaddr * addr )

#include <zephyr/net/stun.h>

Decode an attribute in the XOR-MAPPED-ADDRESS format.

For XOR-MAPPED-ADDRESS itself use stun_get_xor_mapped_address(); this is for the attributes of STUN extensions that share its format.

Parameters
msgResult of stun_parse().
attr_typeAttribute type.
[out]addrCaller-allocated output address with space for a full struct net_sockaddr, regardless of the address family. Use struct net_sockaddr or struct net_sockaddr_storage. Do not pass a smaller family-specific address structure.
Return values
0Success.
-ENOENTNo such attribute.
-EBADMSGThe attribute is malformed.
-EAFNOSUPPORTA family other than IPv4 and IPv6, or an IPv6 address and the IPv6 stack is not enabled.
-EINVALNULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse().

◆ stun_get_xor_mapped_address()

int stun_get_xor_mapped_address ( const struct stun_msg * msg,
struct net_sockaddr * addr )

#include <zephyr/net/stun.h>

Decode XOR-MAPPED-ADDRESS.

Parameters
msgResult of stun_parse().
[out]addrCaller-allocated output address with space for a full struct net_sockaddr, regardless of the address family. Use struct net_sockaddr or struct net_sockaddr_storage. Do not pass a smaller family-specific address structure.
Return values
0Success.
-ENOENTNo XOR-MAPPED-ADDRESS attribute.
-EAFNOSUPPORTA family other than IPv4 and IPv6, or an IPv6 address and the IPv6 stack is not enabled.
-EINVALNULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse().

◆ stun_has_valid_header()

bool stun_has_valid_header ( const uint8_t * buf,
size_t len )

#include <zephyr/net/stun.h>

Check that a datagram starts with a valid STUN header.

Applies the header checks of RFC 8489, section-6.3 that need no state: at least a header long, the two top bits zero, the magic cookie, and a Length that is a multiple of 4 and accounts for the whole datagram. Meant for telling STUN from other protocols on a shared port. The attributes are not looked at: stun_parse() applies the same checks first and may still refuse the message.

Parameters
bufDatagram; NULL has no valid header.
lenIts length.
Returns
true if the datagram has a valid STUN header.

◆ stun_msg_type_compose()

uint16_t stun_msg_type_compose ( uint16_t method,
enum stun_class msg_class )

#include <zephyr/net/stun.h>

Compose a message type.

Parameters
methodMethod, 12 bits.
msg_classMessage class: request, indication, success or error response.
Returns
The 14-bit message type (RFC 8489, section-5).

◆ stun_msg_type_get_class()

enum stun_class stun_msg_type_get_class ( uint16_t type)

#include <zephyr/net/stun.h>

Get the class of a message type.

Parameters
typeMessage type.
Returns
The class.

◆ stun_msg_type_get_method()

uint16_t stun_msg_type_get_method ( uint16_t type)

#include <zephyr/net/stun.h>

Get the method of a message type.

Parameters
typeMessage type.
Returns
The method.

◆ stun_parse()

int stun_parse ( const uint8_t * buf,
size_t len,
struct stun_msg * out )

#include <zephyr/net/stun.h>

Parse one datagram.

The parser applies these rules, from RFC 8489 and, for ICE, RFC 8445; where an RFC leaves the choice open, it takes the stricter one:

  • the message fills the datagram: Length is a multiple of 4 and equals len - 20 (RFC 8489, section-5, RFC 8489, section-6.3);
  • of each attribute type only the first occurrence is processed, later ones are skipped unexamined (RFC 8489, section-14);
  • attributes after MESSAGE-INTEGRITY are ignored, except MESSAGE-INTEGRITY-SHA256 and FINGERPRINT; without MESSAGE-INTEGRITY ahead of it, the boundary is MESSAGE-INTEGRITY-SHA256, and a MESSAGE-INTEGRITY after it is ignored like the rest (RFC 8489, section-9);
  • FINGERPRINT is the last attribute (RFC 8489, section-14.7);
  • an attribute the codec understands must be well-formed, or the whole message is malformed: it has the lengths and values the RFCs fix and at most STUN_TEXT_MAX_LEN bytes of text, whose encoding is not checked;
  • an address attribute of a family other than IPv4 and IPv6 is not judged: the getter reports it (RFC 8489, section-6.3.3);
  • ICE-CONTROLLING and ICE-CONTROLLED together are malformed: an agent sends the attribute of its one role (RFC 8445, section-7.1.3), never both.

Attributes the codec does not understand are skipped; stun_unknown_attrs() reports the comprehension-required ones.

Parameters
bufDatagram.
lenIts length.
[out]outResult. On error it holds no message: the functions that take it return -EINVAL, and the values of its fields are undefined.
Return values
0Success.
-EINVALNULL argument, or not STUN at all: shorter than a header, top bits set, wrong magic cookie.
-EBADMSGMalformed message.

◆ stun_unknown_attrs()

int stun_unknown_attrs ( const struct stun_msg * msg,
const uint16_t * known,
size_t n_known,
uint16_t * out,
size_t cap )

#include <zephyr/net/stun.h>

List the comprehension-required attributes nobody understands.

Lists every attribute of the parsed message that must be understood (comprehension-required, a type of 0x0000 to 0x7FFF) and that neither the codec understands (MAPPED-ADDRESS, USERNAME, MESSAGE-INTEGRITY, ERROR-CODE, UNKNOWN-ATTRIBUTES, REALM, NONCE, MESSAGE-INTEGRITY-SHA256, XOR-MAPPED-ADDRESS, PRIORITY, USE-CANDIDATE) nor the caller, who lists the further types it handles in known.

If the list is not empty, the message cannot be processed (RFC 8489, section-6.3): a request is answered with 420 (Unknown Attribute) and UNKNOWN-ATTRIBUTES, any other message is discarded.

Parameters
msgResult of stun_parse().
knownFurther attribute types the caller understands; may be NULL if n_known is 0.
n_knownNumber of entries in known.
[out]outReceives the types, in order of appearance, each once; may be NULL if cap is 0.
capRoom in out. An unknown attribute is compared with up to cap collected types, and every attribute with the n_known types in known, so the work grows with both.
Returns
The number of types written to out, or cap + 1 if there are more than fit: out then holds the first cap of them.
Return values
-EINVALNULL msg, msg holds no message, or a NULL list with a non-zero count.

◆ stun_verify_fingerprint()

int stun_verify_fingerprint ( const struct stun_msg * msg)

#include <zephyr/net/stun.h>

Verify FINGERPRINT.

Recomputes the CRC-32 of the message ahead of FINGERPRINT, XORs it with 0x5354554E ("STUN" in ASCII) and compares the result with the value of the attribute (RFC 8489, section-14.7). This is no authentication, as there is no key: it tells STUN from other protocols on a shared port and catches a damaged message.

Parameters
msgResult of stun_parse().
Return values
0The fingerprint is correct.
-ENOENTNo FINGERPRINT attribute.
-EBADMSGThe CRC-32 does not match: the message is damaged or not STUN.
-EINVALNULL msg, or msg holds no message.

◆ stun_verify_integrity()

int stun_verify_integrity ( const struct stun_msg * msg,
const uint8_t * key,
size_t key_len )

#include <zephyr/net/stun.h>

Verify MESSAGE-INTEGRITY.

Recomputes the HMAC-SHA1 of RFC 8489, section-14.5 and compares it in constant time. The key is the password for short-term credentials.

Parameters
msgResult of stun_parse().
keyKey. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing.
key_lenIts length, not 0.
Return values
0The message is authentic.
-ENOENTNo MESSAGE-INTEGRITY attribute.
-EBADMSGThe value does not match.
-EINVALNULL argument, empty key, or msg holds no message.
-EIOThe cryptographic backend failed.

◆ stun_verify_integrity_sha256()

int stun_verify_integrity_sha256 ( const struct stun_msg * msg,
const uint8_t * key,
size_t key_len,
size_t min_len )

#include <zephyr/net/stun.h>

Verify MESSAGE-INTEGRITY-SHA256.

Recomputes the HMAC-SHA256 of RFC 8489, section-14.6 and compares it in constant time. The value has to be the full 32 bytes unless the STUN Usage allows truncation, which the caller states with min_len.

Parameters
msgResult of stun_parse().
keyKey. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing.
key_lenIts length, not 0.
min_lenShortest value to accept: 32, or a multiple of 4 not below 16.
Return values
0The message is authentic.
-ENOENTNo MESSAGE-INTEGRITY-SHA256 attribute.
-EBADMSGThe value does not match, or is shorter than min_len.
-EINVALNULL argument, empty key, min_len out of range, or msg holds no message.
-EIOThe cryptographic backend failed.