Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

STUN (Session Traversal Utilities for NAT, RFC 8489) message codec. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <zephyr/net/net_ip.h>

Go to the source code of this file.

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).
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
#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).

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.

Detailed Description

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