|
Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
|
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 | |
| #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). | |
Message codec for STUN (RFC 8489) with the attributes of ICE (RFC 8445).
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.
| #define STUN_ATTR_ERROR_CODE 0x0009U |
#include <zephyr/net/stun.h>
ERROR-CODE.
| #define STUN_ATTR_FINGERPRINT 0x8028U |
#include <zephyr/net/stun.h>
FINGERPRINT.
| #define STUN_ATTR_ICE_CONTROLLED 0x8029U |
#include <zephyr/net/stun.h>
ICE-CONTROLLED (ICE).
| #define STUN_ATTR_ICE_CONTROLLING 0x802AU |
#include <zephyr/net/stun.h>
ICE-CONTROLLING (ICE).
| #define STUN_ATTR_MAPPED_ADDRESS 0x0001U |
#include <zephyr/net/stun.h>
MAPPED-ADDRESS.
| #define STUN_ATTR_MESSAGE_INTEGRITY 0x0008U |
#include <zephyr/net/stun.h>
MESSAGE-INTEGRITY.
| #define STUN_ATTR_MESSAGE_INTEGRITY_SHA256 0x001CU |
#include <zephyr/net/stun.h>
MESSAGE-INTEGRITY-SHA256.
| #define STUN_ATTR_NONCE 0x0015U |
#include <zephyr/net/stun.h>
NONCE.
| #define STUN_ATTR_PRIORITY 0x0024U |
#include <zephyr/net/stun.h>
PRIORITY (ICE).
| #define STUN_ATTR_REALM 0x0014U |
#include <zephyr/net/stun.h>
REALM.
| #define STUN_ATTR_SOFTWARE 0x8022U |
#include <zephyr/net/stun.h>
SOFTWARE.
| #define STUN_ATTR_UNKNOWN_ATTRIBUTES 0x000AU |
#include <zephyr/net/stun.h>
UNKNOWN-ATTRIBUTES.
| #define STUN_ATTR_USE_CANDIDATE 0x0025U |
#include <zephyr/net/stun.h>
USE-CANDIDATE (ICE).
| #define STUN_ATTR_USERNAME 0x0006U |
#include <zephyr/net/stun.h>
USERNAME.
| #define STUN_ATTR_XOR_MAPPED_ADDRESS 0x0020U |
#include <zephyr/net/stun.h>
XOR-MAPPED-ADDRESS.
| #define STUN_BINDING_ERROR_RESPONSE 0x0111U |
#include <zephyr/net/stun.h>
Binding error response.
| #define STUN_BINDING_REQUEST 0x0001U |
#include <zephyr/net/stun.h>
Binding request.
| #define STUN_BINDING_SUCCESS_RESPONSE 0x0101U |
#include <zephyr/net/stun.h>
Binding success response.
| #define STUN_HEADER_SIZE 20U |
#include <zephyr/net/stun.h>
Size of the message header.
| #define STUN_INTEGRITY_LEN 20U |
#include <zephyr/net/stun.h>
Length of the MESSAGE-INTEGRITY value, an HMAC-SHA1.
| #define STUN_INTEGRITY_SHA256_MAX_LEN 32U |
#include <zephyr/net/stun.h>
Length of a MESSAGE-INTEGRITY-SHA256 value that is not truncated.
| #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).
| #define STUN_MAGIC_COOKIE 0x2112A442UL |
#include <zephyr/net/stun.h>
Magic cookie, the second 32-bit word of every message (RFC 8489, section-5).
| #define STUN_METHOD_BINDING 0x001U |
#include <zephyr/net/stun.h>
Binding method (RFC 8489, section-18.2).
| #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).
| #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).
| #define STUN_TXID_SIZE 12U |
#include <zephyr/net/stun.h>
Size of the transaction id.
| #define STUN_USERNAME_MAX_LEN 508U |
#include <zephyr/net/stun.h>
Longest USERNAME the builder sends, in bytes (RFC 8489, section-14.3).
| 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. |
| 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.
| [in,out] | builder | Builder. |
| attr_type | Attribute type. | |
| value | Value; may be NULL if value_len is 0. | |
| value_len | Its length, at most 65535. |
| 0 | Success. |
| -EINVAL | builder 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. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [in,out] | builder | Builder. |
| code | Error code, 300 to 699. | |
| reason | Reason phrase, at most STUN_TEXT_MAX_CHARS UTF-8 characters; NULL for none. |
| 0 | Success. |
| -EINVAL | builder 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. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [in,out] | builder | Builder. |
| 0 | Success. |
| -EINVAL | builder is NULL. |
| -EPERM | FINGERPRINT has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_ice_controlled | ( | struct stun_builder * | builder, |
| uint64_t | tiebreaker ) |
#include <zephyr/net/stun.h>
Add ICE-CONTROLLED.
| [in,out] | builder | Builder. |
| tiebreaker | Tie-breaker of the agent (RFC 8445, section-7.1.3). |
| 0 | Success. |
| -EINVAL | builder is NULL. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_ice_controlling | ( | struct stun_builder * | builder, |
| uint64_t | tiebreaker ) |
#include <zephyr/net/stun.h>
Add ICE-CONTROLLING.
| [in,out] | builder | Builder. |
| tiebreaker | Tie-breaker of the agent (RFC 8445, section-7.1.3). |
| 0 | Success. |
| -EINVAL | builder is NULL. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [in,out] | builder | Builder. |
| key | Key. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing. | |
| key_len | Its length, not 0. |
| 0 | Success. |
| -EINVAL | builder or key is NULL, or key_len is 0. |
| -EPERM | MESSAGE-INTEGRITY or a later closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | The PSA backend failed to compute the HMAC, now or in an earlier call. |
| 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.
| [in,out] | builder | Builder. |
| key | Key. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing. | |
| key_len | Its length, not 0. |
| 0 | Success. |
| -EINVAL | builder or key is NULL, or key_len is 0. |
| -EPERM | MESSAGE-INTEGRITY-SHA256 or FINGERPRINT has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | The PSA backend failed to compute the HMAC, now or in an earlier call. |
| int stun_add_priority | ( | struct stun_builder * | builder, |
| uint32_t | priority ) |
#include <zephyr/net/stun.h>
Add PRIORITY.
| [in,out] | builder | Builder. |
| priority | Priority of the candidate (RFC 8445, section-7.1.1). |
| 0 | Success. |
| -EINVAL | builder is NULL. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_software | ( | struct stun_builder * | builder, |
| const char * | sw ) |
#include <zephyr/net/stun.h>
Add SOFTWARE.
| [in,out] | builder | Builder. |
| sw | Description of the software, at most STUN_TEXT_MAX_CHARS UTF-8 characters. |
| 0 | Success. |
| -EINVAL | builder 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. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [in,out] | builder | Builder. |
| types | Attribute types; may be NULL if n_types is 0. | |
| n_types | Number of types. |
| 0 | Success. |
| -EINVAL | builder is NULL, types is NULL while n_types is not 0, or n_types is over 32767. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_use_candidate | ( | struct stun_builder * | builder | ) |
#include <zephyr/net/stun.h>
Add USE-CANDIDATE.
| [in,out] | builder | Builder. |
| 0 | Success. |
| -EINVAL | builder is NULL. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_username | ( | struct stun_builder * | builder, |
| const char * | username ) |
#include <zephyr/net/stun.h>
Add USERNAME.
| [in,out] | builder | Builder. |
| username | User name, at most STUN_USERNAME_MAX_LEN bytes, already processed with the OpaqueString profile (RFC 8265). |
| 0 | Success. |
| -EINVAL | builder 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. |
| -EPERM | A closing attribute has been added already. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [in,out] | builder | Builder. |
| attr_type | Attribute type. | |
| addr | IPv4 or IPv6 address and port. |
| 0 | Success. |
| -EINVAL | builder or addr is NULL, or attr_type is one of the closing attributes. |
| -EPERM | A closing attribute has been added already. |
| -EAFNOSUPPORT | The family of addr is neither IPv4 nor IPv6, or it is IPv6 and CONFIG_NET_IPV6 is not enabled. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| int stun_add_xor_mapped_address | ( | struct stun_builder * | builder, |
| const struct net_sockaddr * | addr ) |
#include <zephyr/net/stun.h>
Add XOR-MAPPED-ADDRESS.
| [in,out] | builder | Builder. |
| addr | IPv4 or IPv6 address and port. |
| 0 | Success. |
| -EINVAL | builder or addr is NULL. |
| -EPERM | A closing attribute has been added already. |
| -EAFNOSUPPORT | The family of addr is neither IPv4 nor IPv6, or it is IPv6 and CONFIG_NET_IPV6 is not enabled. |
| -EMSGSIZE | The attribute does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| [out] | builder | Builder. |
| [out] | buf | Buffer for the message. |
| buf_size | Its size, at least STUN_HEADER_SIZE. | |
| msg_type | Message type, 14 bits: the two top bits are zero (RFC 8489, section-5). | |
| transaction_id | Transaction id. For a request it has to come from a cryptographically secure random generator (RFC 8489, section-5). |
| 0 | Success. |
| -EINVAL | builder, buf or transaction_id is NULL, or msg_type has one of its two top bits set. |
| -EMSGSIZE | buf_size is below STUN_HEADER_SIZE. |
| int stun_builder_len | ( | const struct stun_builder * | builder | ) |
#include <zephyr/net/stun.h>
Get the length of the message built so far.
| builder | Builder. |
| -EINVAL | builder is NULL. |
| -EMSGSIZE | An earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| msg | Result of stun_parse(). | |
| attr_type | Attribute type. | |
| [out] | value | Receives a pointer to the value, inside the parsed buffer; written only on success. |
| [out] | value_len | Receives the length of the value, without padding; written only on success. |
| 0 | Success. |
| -ENOENT | No attribute of the type ahead of the integrity boundary. |
| -EINVAL | NULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse(). |
| 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.
| [in,out] | builder | Builder. |
| key | Key. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing. | |
| key_len | Its length, not 0. |
| -EINVAL | builder or key is NULL, or key_len is 0. |
| -EPERM | MESSAGE-INTEGRITY or a later closing attribute has been added already. |
| -EMSGSIZE | The closing attributes do not fit, or an earlier call ran out of room. |
| -EIO | The PSA backend failed to compute the HMAC, now or in an earlier call. |
| 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.
| [in,out] | builder | Builder. |
| -EINVAL | builder is NULL. |
| -EPERM | FINGERPRINT has been added already. |
| -EMSGSIZE | FINGERPRINT does not fit, or an earlier call ran out of room. |
| -EIO | An earlier HMAC failed in the PSA backend. |
| 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.
| msg | Result of stun_parse(). | |
| attr_type | Attribute type. | |
| [out] | addr | Caller-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. |
| 0 | Success. |
| -ENOENT | No such attribute. |
| -EBADMSG | The attribute is malformed. |
| -EAFNOSUPPORT | A family other than IPv4 and IPv6, or an IPv6 address and the IPv6 stack is not enabled. |
| -EINVAL | NULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse(). |
| int stun_get_xor_mapped_address | ( | const struct stun_msg * | msg, |
| struct net_sockaddr * | addr ) |
#include <zephyr/net/stun.h>
Decode XOR-MAPPED-ADDRESS.
| msg | Result of stun_parse(). | |
| [out] | addr | Caller-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. |
| 0 | Success. |
| -ENOENT | No XOR-MAPPED-ADDRESS attribute. |
| -EAFNOSUPPORT | A family other than IPv4 and IPv6, or an IPv6 address and the IPv6 stack is not enabled. |
| -EINVAL | NULL argument, msg holds no message, or the attribute runs past the end of the message because the buffer changed after stun_parse(). |
#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.
| buf | Datagram; NULL has no valid header. |
| len | Its length. |
| uint16_t stun_msg_type_compose | ( | uint16_t | method, |
| enum stun_class | msg_class ) |
#include <zephyr/net/stun.h>
Compose a message type.
| method | Method, 12 bits. |
| msg_class | Message class: request, indication, success or error response. |
| enum stun_class stun_msg_type_get_class | ( | uint16_t | type | ) |
#include <zephyr/net/stun.h>
Get the class of a message type.
| type | Message type. |
#include <zephyr/net/stun.h>
Get the method of a message type.
| type | Message type. |
#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:
len - 20 (RFC 8489, section-5, RFC 8489, section-6.3);Attributes the codec does not understand are skipped; stun_unknown_attrs() reports the comprehension-required ones.
| buf | Datagram. | |
| len | Its length. | |
| [out] | out | Result. On error it holds no message: the functions that take it return -EINVAL, and the values of its fields are undefined. |
| 0 | Success. |
| -EINVAL | NULL argument, or not STUN at all: shorter than a header, top bits set, wrong magic cookie. |
| -EBADMSG | Malformed message. |
| 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.
| msg | Result of stun_parse(). | |
| known | Further attribute types the caller understands; may be NULL if n_known is 0. | |
| n_known | Number of entries in known. | |
| [out] | out | Receives the types, in order of appearance, each once; may be NULL if cap is 0. |
| cap | Room 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. |
out, or cap + 1 if there are more than fit: out then holds the first cap of them. | -EINVAL | NULL msg, msg holds no message, or a NULL list with a non-zero count. |
| 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.
| msg | Result of stun_parse(). |
| 0 | The fingerprint is correct. |
| -ENOENT | No FINGERPRINT attribute. |
| -EBADMSG | The CRC-32 does not match: the message is damaged or not STUN. |
| -EINVAL | NULL msg, or msg holds no message. |
#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.
| msg | Result of stun_parse(). |
| key | Key. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing. |
| key_len | Its length, not 0. |
| 0 | The message is authentic. |
| -ENOENT | No MESSAGE-INTEGRITY attribute. |
| -EBADMSG | The value does not match. |
| -EINVAL | NULL argument, empty key, or msg holds no message. |
| -EIO | The cryptographic backend failed. |
| 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.
| msg | Result of stun_parse(). |
| key | Key. For short-term credentials, the password processed with the OpaqueString profile (RFC 8265); ICE passwords are ASCII and need no processing. |
| key_len | Its length, not 0. |
| min_len | Shortest value to accept: 32, or a multiple of 4 not below 16. |
| 0 | The message is authentic. |
| -ENOENT | No MESSAGE-INTEGRITY-SHA256 attribute. |
| -EBADMSG | The value does not match, or is shorter than min_len. |
| -EINVAL | NULL argument, empty key, min_len out of range, or msg holds no message. |
| -EIO | The cryptographic backend failed. |