diff --git a/include/re_stun.h b/include/re_stun.h index 0add3d2..7fbe6aa 100644 --- a/include/re_stun.h +++ b/include/re_stun.h @@ -99,6 +99,7 @@ struct stun_even_port { bool r; }; +/** Defines a STUN attribute */ struct stun_attr { struct le le; uint16_t type; @@ -145,12 +146,13 @@ struct stun_attr { }; +/** STUN Configuration */ struct stun_conf { - uint32_t rto; - uint32_t rc; - uint32_t rm; - uint32_t ti; - uint8_t tos; /**< Type-of-service field */ + uint32_t rto; /**< RTO Retransmission TimeOut [ms] */ + uint32_t rc; /**< Rc Retransmission count (default 7) */ + uint32_t rm; /**< Rm Max retransmissions (default 16) */ + uint32_t ti; /**< Ti Timeout for reliable transport [ms] */ + uint8_t tos; /**< Type-of-service field */ }; diff --git a/mk/Doxyfile b/mk/Doxyfile index 1f66830..5482851 100644 --- a/mk/Doxyfile +++ b/mk/Doxyfile @@ -89,8 +89,7 @@ FILE_PATTERNS = *.c \ RECURSIVE = YES EXCLUDE = test.c \ include/re_bitv.h \ - src/md5/md5.h src/md5/md5.c \ - src/stun include/re_stun.h + src/md5/md5.h src/md5/md5.c EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = */.svn/* diff --git a/src/stun/attr.c b/src/stun/attr.c index 88f0efc..de31b09 100644 --- a/src/stun/attr.c +++ b/src/stun/attr.c @@ -348,6 +348,13 @@ int stun_attr_decode(struct stun_attr **attrp, struct mbuf *mb, } +/** + * Get the name of a STUN attribute + * + * @param type STUN attribute type + * + * @return String with attribute name + */ const char *stun_attr_name(uint16_t type) { switch (type) { diff --git a/src/stun/ctrans.c b/src/stun/ctrans.c index db294e4..54643fd 100644 --- a/src/stun/ctrans.c +++ b/src/stun/ctrans.c @@ -152,6 +152,15 @@ static void tcp_close_handler(int err, void *arg) } +/** + * Handle an incoming STUN message to a Client Transaction + * + * @param stun STUN instance + * @param msg STUN message + * @param ua Unknown attributes + * + * @return 0 if success, otherwise errorcode + */ int stun_ctrans_recv(struct stun *stun, const struct stun_msg *msg, const struct stun_unknown_attr *ua) { diff --git a/src/stun/ind.c b/src/stun/ind.c index 9988dbd..cd6f364 100644 --- a/src/stun/ind.c +++ b/src/stun/ind.c @@ -13,6 +13,23 @@ #include "stun.h" +/** + * Send a STUN Indication message + * + * @param proto Transport Protocol + * @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn) + * @param dst Destination network address + * @param presz Number of bytes in preamble, if sending over TURN + * @param method STUN Method + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param attrc Number of attributes to encode (variable arguments) + * @param ... Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_indication(int proto, void *sock, const struct sa *dst, size_t presz, uint16_t method, const uint8_t *key, size_t keylen, bool fp, uint32_t attrc, ...) diff --git a/src/stun/msg.c b/src/stun/msg.c index c8ca4bf..dda3d8d 100644 --- a/src/stun/msg.c +++ b/src/stun/msg.c @@ -68,6 +68,12 @@ static void destructor(void *arg) /** * Decode a buffer to a STUN Message * + * @param msgpp Pointer to allocation STUN message + * @param mb Buffer containing the raw STUN packet + * @param ua Unknown attributes (optional) + * + * @return 0 if success, otherwise errorcode + * * @note `mb' will be referenced */ int stun_msg_decode(struct stun_msg **msgpp, struct mbuf *mb, @@ -127,36 +133,79 @@ int stun_msg_decode(struct stun_msg **msgpp, struct mbuf *mb, } +/** + * Get the STUN message type + * + * @param msg STUN Message + * + * @return STUN Message type + */ uint16_t stun_msg_type(const struct stun_msg *msg) { return msg ? msg->hdr.type : 0; } +/** + * Get the STUN message class + * + * @param msg STUN Message + * + * @return STUN Message class + */ uint16_t stun_msg_class(const struct stun_msg *msg) { return STUN_CLASS(stun_msg_type(msg)); } +/** + * Get the STUN message method + * + * @param msg STUN Message + * + * @return STUN Message method + */ uint16_t stun_msg_method(const struct stun_msg *msg) { return STUN_METHOD(stun_msg_type(msg)); } +/** + * Get the STUN message Transaction-ID + * + * @param msg STUN Message + * + * @return STUN Message Transaction-ID + */ const uint8_t *stun_msg_tid(const struct stun_msg *msg) { return msg ? msg->hdr.tid : NULL; } +/** + * Check if a STUN Message has the magic cookie + * + * @param msg STUN Message + * + * @return true if Magic Cookie, otherwise false + */ bool stun_msg_mcookie(const struct stun_msg *msg) { return msg && (STUN_MAGIC_COOKIE == msg->hdr.cookie); } +/** + * Lookup a STUN attribute in a STUN message + * + * @param msg STUN Message + * @param type STUN Attribute type + * + * @return STUN Attribute if found, otherwise NULL + */ struct stun_attr *stun_msg_attr(const struct stun_msg *msg, uint16_t type) { struct le *le = msg ? list_head(&msg->attrl) : NULL; @@ -174,6 +223,15 @@ struct stun_attr *stun_msg_attr(const struct stun_msg *msg, uint16_t type) } +/** + * Apply a function handler to all STUN attribute + * + * @param msg STUN Message + * @param h Attribute handler + * @param arg Handler argument + * + * @return STUN attribute if handler returned true, otherwise NULL + */ struct stun_attr *stun_msg_attr_apply(const struct stun_msg *msg, stun_attr_h *h, void *arg) { @@ -192,6 +250,24 @@ struct stun_attr *stun_msg_attr_apply(const struct stun_msg *msg, } +/** + * Encode a STUN message + * + * @param mb Buffer to encode message into + * @param method STUN Method + * @param class STUN Method class + * @param tid Transaction ID + * @param ec STUN error code (optional) + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param padding Padding byte + * @param attrc Number of attributes to encode (variable arguments) + * @param ap Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_msg_vencode(struct mbuf *mb, uint16_t method, uint8_t class, const uint8_t *tid, const struct stun_errcode *ec, const uint8_t *key, size_t keylen, bool fp, @@ -265,6 +341,24 @@ int stun_msg_vencode(struct mbuf *mb, uint16_t method, uint8_t class, } +/** + * Encode a STUN message + * + * @param mb Buffer to encode message into + * @param method STUN Method + * @param class STUN Method class + * @param tid Transaction ID + * @param ec STUN error code (optional) + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param padding Padding byte + * @param attrc Number of attributes to encode (variable arguments) + * @param ... Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_msg_encode(struct mbuf *mb, uint16_t method, uint8_t class, const uint8_t *tid, const struct stun_errcode *ec, const uint8_t *key, size_t keylen, bool fp, @@ -282,6 +376,15 @@ int stun_msg_encode(struct mbuf *mb, uint16_t method, uint8_t class, } +/** + * Verify the Message-Integrity of a STUN message + * + * @param msg STUN Message + * @param key Authentication key + * @param keylen Number of bytes in authentication key + * + * @return 0 if verified, otherwise errorcode + */ int stun_msg_chk_mi(const struct stun_msg *msg, const uint8_t *key, size_t keylen) { @@ -321,6 +424,13 @@ int stun_msg_chk_mi(const struct stun_msg *msg, const uint8_t *key, } +/** + * Check the Fingerprint of a STUN message + * + * @param msg STUN Message + * + * @return 0 if fingerprint matches, otherwise errorcode + */ int stun_msg_chk_fingerprint(const struct stun_msg *msg) { struct stun_attr *fp; @@ -355,6 +465,11 @@ static bool attr_print(const struct stun_attr *attr, void *arg) } +/** + * Print a STUN message to STDOUT + * + * @param msg STUN Message + */ void stun_msg_dump(const struct stun_msg *msg) { if (!msg) diff --git a/src/stun/rep.c b/src/stun/rep.c index 2e780f4..11ffbfd 100644 --- a/src/stun/rep.c +++ b/src/stun/rep.c @@ -12,6 +12,23 @@ #include "stun.h" +/** + * Send a STUN response message + * + * @param proto Transport Protocol + * @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn) + * @param dst Destination network address + * @param presz Number of bytes in preamble, if sending over TURN + * @param req Matching STUN request + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param attrc Number of attributes to encode (variable arguments) + * @param ... Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_reply(int proto, void *sock, const struct sa *dst, size_t presz, const struct stun_msg *req, const uint8_t *key, size_t keylen, bool fp, uint32_t attrc, ...) @@ -46,6 +63,25 @@ int stun_reply(int proto, void *sock, const struct sa *dst, size_t presz, } +/** + * Send a STUN error response + * + * @param proto Transport Protocol + * @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn) + * @param dst Destination network address + * @param presz Number of bytes in preamble, if sending over TURN + * @param req Matching STUN request + * @param scode Status code + * @param reason Reason string + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param attrc Number of attributes to encode (variable arguments) + * @param ... Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_ereply(int proto, void *sock, const struct sa *dst, size_t presz, const struct stun_msg *req, uint16_t scode, const char *reason, const uint8_t *key, size_t keylen, diff --git a/src/stun/req.c b/src/stun/req.c index 45da5f4..32e127d 100644 --- a/src/stun/req.c +++ b/src/stun/req.c @@ -13,6 +13,27 @@ #include "stun.h" +/** + * Send a STUN request using a client transaction + * + * @param ctp Pointer to allocated client transaction (optional) + * @param stun STUN Instance + * @param proto Transport Protocol + * @param sock Socket; UDP (struct udp_sock) or TCP (struct tcp_conn) + * @param dst Destination network address + * @param presz Number of bytes in preamble, if sending over TURN + * @param method STUN Method + * @param key Authentication key (optional) + * @param keylen Number of bytes in authentication key + * @param fp Use STUN Fingerprint attribute + * @param resph Response handler + * @param arg Response handler argument + * @param attrc Number of attributes to encode (variable arguments) + * @param ... Variable list of attribute-tuples + * Each attribute has 2 arguments, attribute type and value + * + * @return 0 if success, otherwise errorcode + */ int stun_request(struct stun_ctrans **ctp, struct stun *stun, int proto, void *sock, const struct sa *dst, size_t presz, uint16_t method, const uint8_t *key, size_t keylen, bool fp, diff --git a/src/stun/stun.c b/src/stun/stun.c index cec8347..4eb3562 100644 --- a/src/stun/stun.c +++ b/src/stun/stun.c @@ -36,6 +36,16 @@ static void destructor(void *arg) } +/** + * Allocate a new STUN instance + * + * @param stunp Pointer to allocated STUN instance + * @param conf STUN configuration (optional) + * @param indh STUN Indication handler (optional) + * @param arg STUN Indication handler argument + * + * @return 0 if success, otherwise errorcode + */ int stun_alloc(struct stun **stunp, const struct stun_conf *conf, stun_ind_h *indh, void *arg) { @@ -58,12 +68,29 @@ int stun_alloc(struct stun **stunp, const struct stun_conf *conf, } +/** + * Get STUN configuration object + * + * @param stun STUN Instance + * + * @return STUN configuration + */ struct stun_conf *stun_conf(struct stun *stun) { return stun ? &stun->conf : NULL; } +/** + * Send a STUN message + * + * @param proto Transport protocol (IPPROTO_UDP or IPPROTO_TCP) + * @param sock Socket, UDP (struct udp_sock) or TCP (struct tcp_conn) + * @param dst Destination network address (UDP only) + * @param mb Buffer containing the STUN message + * + * @return 0 if success, otherwise errorcode + */ int stun_send(int proto, void *sock, const struct sa *dst, struct mbuf *mb) { int err; @@ -90,6 +117,14 @@ int stun_send(int proto, void *sock, const struct sa *dst, struct mbuf *mb) } +/** + * Receive a STUN message + * + * @param stun STUN Instance + * @param mb Buffer containing STUN message + * + * @return 0 if success, otherwise errorcode + */ int stun_recv(struct stun *stun, struct mbuf *mb) { struct stun_unknown_attr ua; @@ -128,6 +163,14 @@ int stun_recv(struct stun *stun, struct mbuf *mb) } +/** + * Print STUN instance debug information + * + * @param pf Print function + * @param stun STUN Instance + * + * @return 0 if success, otherwise errorcode + */ int stun_debug(struct re_printf *pf, const struct stun *stun) { if (!stun)