stun.h File Reference

STUN support. More...

#include "asterisk/network.h"
#include "asterisk/logger_category.h"

Include dependency graph for stun.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	AST_DEBUG_CATEGORY_STUN   ast_debug_category_stun_id() /* STUN debug logging category id */
#define	AST_DEBUG_CATEGORY_STUN_PACKET   ast_debug_category_stun_packet_id() /* STUN packet debug logging category id */
#define	ast_debug_stun(sublevel, ...)    ast_debug_category(sublevel, AST_DEBUG_CATEGORY_STUN, __VA_ARGS__)
	Log debug level STUN information. More...
#define	ast_debug_stun_packet_is_allowed    ast_debug_category_is_allowed(AST_LOG_CATEGORY_ENABLED, AST_DEBUG_CATEGORY_STUN_PACKET)
#define	AST_LOG_CATEGORY_STUN   "stun"
#define	AST_LOG_CATEGORY_STUN_PACKET   "stun_packet"

Typedefs
typedef int()	stun_cb_f(struct stun_attr *attr, void *arg)
	callback type to be invoked on stun responses. More...

Enumerations
enum	ast_stun_result { AST_STUN_IGNORE = 0 , AST_STUN_ACCEPT }

Functions
uintmax_t	ast_debug_category_stun_id (void)
uintmax_t	ast_debug_category_stun_packet_id (void)
int	ast_stun_handle_packet (int s, struct sockaddr_in *src, unsigned char *data, size_t len, stun_cb_f *stun_cb, void *arg)
	handle an incoming STUN message. More...
int	ast_stun_request (int s, struct sockaddr_in *dst, const char *username, struct sockaddr_in *answer)
	Generic STUN request. More...

Variables
static const int	STANDARD_STUN_PORT = 3478

Detailed Description

STUN support.

STUN is defined in RFC 3489.

Definition in file stun.h.

Macro Definition Documentation

AST_DEBUG_CATEGORY_STUN

#define AST_DEBUG_CATEGORY_STUN   ast_debug_category_stun_id() /* STUN debug logging category id */

Definition at line 45 of file stun.h.

AST_DEBUG_CATEGORY_STUN_PACKET

#define AST_DEBUG_CATEGORY_STUN_PACKET   ast_debug_category_stun_packet_id() /* STUN packet debug logging category id */

Definition at line 46 of file stun.h.

ast_debug_stun

#define ast_debug_stun	(		sublevel,
			...
	)		ast_debug_category(sublevel, AST_DEBUG_CATEGORY_STUN, __VA_ARGS__)

Log debug level STUN information.

Parameters

sublevel	Debug output sublevel (>= 0)
...	String format and any associated arguments

Definition at line 54 of file stun.h.

ast_debug_stun_packet_is_allowed

#define ast_debug_stun_packet_is_allowed    ast_debug_category_is_allowed(AST_LOG_CATEGORY_ENABLED, AST_DEBUG_CATEGORY_STUN_PACKET)

Definition at line 58 of file stun.h.

AST_LOG_CATEGORY_STUN

#define AST_LOG_CATEGORY_STUN   "stun"

Definition at line 38 of file stun.h.

AST_LOG_CATEGORY_STUN_PACKET

#define AST_LOG_CATEGORY_STUN_PACKET   "stun_packet"

Definition at line 40 of file stun.h.

Typedef Documentation

stun_cb_f

typedef int() stun_cb_f(struct stun_attr *attr, void *arg)

callback type to be invoked on stun responses.

Definition at line 95 of file stun.h.

Enumeration Type Documentation

ast_stun_result

enum ast_stun_result

Enumerator
AST_STUN_IGNORE
AST_STUN_ACCEPT

Definition at line 63 of file stun.h.

                     {
    AST_STUN_IGNORE = 0,
    AST_STUN_ACCEPT,
};

Function Documentation

ast_debug_category_stun_id()

uintmax_t ast_debug_category_stun_id

(

void

)

Definition at line 555 of file stun.c.

{
    return debug_category_stun_id;
}

References debug_category_stun_id.

ast_debug_category_stun_packet_id()

uintmax_t ast_debug_category_stun_packet_id

(

void

)

Definition at line 562 of file stun.c.

{
    return debug_category_stun_packet_id;
}

References debug_category_stun_packet_id.

ast_stun_handle_packet()

int ast_stun_handle_packet	(	int	s,
		struct sockaddr_in *	src,
		unsigned char *	data,
		size_t	len,
		stun_cb_f *	stun_cb,
		void *	arg
	)

handle an incoming STUN message.

Parameters

s	Socket to send any response to.
src	Address where packet came from.
data	STUN packet buffer to process.
len	Length of packet
stun_cb	If not NULL, callback for each STUN attribute.
arg	Arg to pass to callback.

Do some basic sanity checks on packet size and content, try to extract a bit of information, and possibly reply. At the moment this only processes BIND requests, and returns the externally visible address of the request. If a callback is specified, invoke it with the attribute.

Return values

AST_STUN_ACCEPT	if responed to a STUN request
AST_STUN_IGNORE
-1	on error

Definition at line 293 of file stun.c.

{
    struct stun_header *hdr = (struct stun_header *)data;
    struct stun_attr *attr;
    struct stun_state st;
    int ret = AST_STUN_IGNORE;
    int x;
 
    /* On entry, 'len' is the length of the udp payload. After the
     * initial checks it becomes the size of unprocessed options,
     * while 'data' is advanced accordingly.
     */
    if (len < sizeof(struct stun_header)) {
        ast_debug_stun(1, "Runt STUN packet (only %d, wanting at least %d)\n", (int) len, (int) sizeof(struct stun_header));
        return -1;
    }
    len -= sizeof(struct stun_header);
    data += sizeof(struct stun_header);
    x = ntohs(hdr->msglen); /* len as advertised in the message */
    if (ast_debug_stun_packet_is_allowed)
        ast_verbose("STUN Packet, msg %s (%04x), length: %d\n", stun_msg2str(ntohs(hdr->msgtype)), (unsigned)ntohs(hdr->msgtype), x);
    if (x > len) {
        ast_debug_stun(1, "Scrambled STUN packet length (got %d, expecting %d)\n", x, (int)len);
    } else
        len = x;
    memset(&st, 0, sizeof(st));
    while (len) {
        if (len < sizeof(struct stun_attr)) {
            ast_debug_stun(1, "Runt Attribute (got %d, expecting %d)\n", (int)len, (int) sizeof(struct stun_attr));
            break;
        }
        attr = (struct stun_attr *)data;
        /* compute total attribute length */
        x = ntohs(attr->len) + sizeof(struct stun_attr);
        if (x > len) {
            ast_debug_stun(1, "Inconsistent Attribute (length %d exceeds remaining msg len %d)\n", x, (int)len);
            break;
        }
        if (stun_cb)
            stun_cb(attr, arg);
        if (stun_process_attr(&st, attr)) {
            ast_debug_stun(1, "Failed to handle attribute %s (%04x)\n", stun_attr2str(ntohs(attr->attr)), (unsigned)ntohs(attr->attr));
            break;
        }
        /* Clear attribute id: in case previous entry was a string,
         * this will act as the terminator for the string.
         */
        attr->attr = 0;
        data += x;
        len -= x;
    }
    /* Null terminate any string.
     * XXX NOTE, we write past the size of the buffer passed by the
     * caller, so this is potentially dangerous. The only thing that
     * saves us is that usually we read the incoming message in a
     * much larger buffer in the struct ast_rtp
     */
    *data = '\0';
 
    /* Now prepare to generate a reply, which at the moment is done
     * only for properly formed (len == 0) STUN_BINDREQ messages.
     */
    if (len == 0) {
        unsigned char respdata[1024];
        struct stun_header *resp = (struct stun_header *)respdata;
        int resplen = 0;    /* len excluding header */
        int respleft = sizeof(respdata) - sizeof(struct stun_header);
        char combined[33];
 
        resp->id = hdr->id;
        resp->msgtype = 0;
        resp->msglen = 0;
        attr = (struct stun_attr *)resp->ies;
        switch (ntohs(hdr->msgtype)) {
        case STUN_BINDREQ:
            if (ast_debug_stun_packet_is_allowed)
                ast_verbose("STUN Bind Request, username: %s\n",
                        st.username ? st.username : "<none>");
            if (st.username) {
                append_attr_string(&attr, STUN_USERNAME, st.username, &resplen, &respleft);
                /*
                 * For Google Voice, the stun username is made up of the local
                 * and remote usernames, each being fixed at 16 bytes.  We have
                 * to swap the two at this point.
                 */
                snprintf(combined, 17, "%16s", st.username + 16);
                snprintf(combined + 16, 17, "%16s", st.username);
            } else {
                combined[0] = '\0';
            }
 
            append_attr_address(&attr, STUN_MAPPED_ADDRESS, src, &resplen, &respleft);
            resp->msglen = htons(resplen);
            resp->msgtype = htons(STUN_BINDRESP);
            stun_send(s, src, resp);
            ast_stun_request(s, src, combined, NULL);
            ret = AST_STUN_ACCEPT;
            break;
        default:
            if (ast_debug_stun_packet_is_allowed)
                ast_verbose("Dunno what to do with STUN message %04x (%s)\n", (unsigned)ntohs(hdr->msgtype), stun_msg2str(ntohs(hdr->msgtype)));
        }
    }
    return ret;
}

References append_attr_address(), append_attr_string(), ast_debug_stun, ast_debug_stun_packet_is_allowed, AST_STUN_ACCEPT, AST_STUN_IGNORE, ast_stun_request(), ast_verbose(), stun_attr::attr, stun_header::id, stun_header::ies, len(), stun_header::msglen, stun_header::msgtype, NULL, stun_attr2str(), STUN_BINDREQ, STUN_BINDRESP, STUN_MAPPED_ADDRESS, stun_msg2str(), stun_process_attr(), stun_send(), STUN_USERNAME, and stun_state::username.

Referenced by ast_rtcp_read(), ast_rtp_read(), and ast_stun_request().

ast_stun_request()

int ast_stun_request	(	int	s,
		struct sockaddr_in *	dst,
		const char *	username,
		struct sockaddr_in *	answer
	)

Generic STUN request.

Parameters

s	The socket used to send the request.
dst	If non null, the address of the STUN server. Only needed if the socket is not bound or connected.
username	If non null, add the username in the request.
answer	If non null, the function waits for a response and puts here the externally visible address.

Send a generic STUN request to the server specified, possibly waiting for a reply and filling the answer parameter with the externally visible address. Note that in this case the request will be blocking.

Note

The interface may change slightly in the future.

Return values

0	on success.
<0	on error.
>0	on timeout.

Definition at line 415 of file stun.c.

{
    struct stun_header *req;
    struct stun_header *rsp;
    unsigned char req_buf[1024];
    unsigned char rsp_buf[1024];
    int reqlen, reqleft;
    struct stun_attr *attr;
    int res = -1;
    int retry;
 
    if (answer) {
        /* Always clear answer in case the request fails. */
        memset(answer, 0, sizeof(struct sockaddr_in));
    }
 
    /* Create STUN bind request */
    req = (struct stun_header *) req_buf;
    stun_req_id(req);
    reqlen = 0;
    reqleft = sizeof(req_buf) - sizeof(struct stun_header);
    attr = (struct stun_attr *) req->ies;
    if (username) {
        append_attr_string(&attr, STUN_USERNAME, username, &reqlen, &reqleft);
    }
    req->msglen = htons(reqlen);
    req->msgtype = htons(STUN_BINDREQ);
 
    for (retry = 0; retry++ < STUN_MAX_RETRIES;) {  /* XXX make retries configurable */
        /* send request, possibly wait for reply */
        struct sockaddr_in src;
        socklen_t srclen;
        struct timeval start;
 
        /* Send STUN message. */
        res = stun_send(s, dst, req);
        if (res < 0) {
            ast_debug_stun(1, "stun_send try %d failed: %s\n", retry, strerror(errno));
            break;
        }
        if (!answer) {
            /* Successful send since we don't care about any response. */
            res = 0;
            break;
        }
 
        start = ast_tvnow();
try_again:
        /* Wait for response. */
        {
            struct pollfd pfds = { .fd = s, .events = POLLIN };
            int ms;
 
            ms = ast_remaining_ms(start, 3000);
            if (ms <= 0) {
                /* No response, timeout */
                handle_stun_timeout(retry, dst);
                res = 1;
                continue;
            }
            res = ast_poll(&pfds, 1, ms);
            if (res < 0) {
                /* Error */
                continue;
            }
            if (!res) {
                /* No response, timeout */
                handle_stun_timeout(retry, dst);
                res = 1;
                continue;
            }
        }
 
        /* Read STUN response. */
        memset(&src, 0, sizeof(src));
        srclen = sizeof(src);
        /* XXX pass sizeof(rsp_buf) - 1 in the size, because stun_handle_packet might
         * write past the end of the buffer.
         */
        res = recvfrom(s, rsp_buf, sizeof(rsp_buf) - 1,
            0, (struct sockaddr *) &src, &srclen);
        if (res < 0) {
            ast_debug_stun(1, "recvfrom try %d failed: %s\n", retry, strerror(errno));
            break;
        }
 
        /* Process the STUN response. */
        rsp = (struct stun_header *) rsp_buf;
        if (ast_stun_handle_packet(s, &src, rsp_buf, res, stun_get_mapped, answer)
            || (rsp->msgtype != htons(STUN_BINDRESP)
                && rsp->msgtype != htons(STUN_BINDERR))
            || stun_id_cmp(&req->id, &rsp->id)) {
            /* Bad STUN packet, not right type, or transaction ID did not match. */
            memset(answer, 0, sizeof(struct sockaddr_in));
 
            /* Was not a resonse to our request. */
            goto try_again;
        }
        /* Success.  answer contains the external address if available. */
        res = 0;
        break;
    }
    return res;
}

References answer(), append_attr_string(), ast_debug_stun, ast_poll, ast_remaining_ms(), ast_stun_handle_packet(), ast_tvnow(), stun_attr::attr, errno, handle_stun_timeout(), stun_header::id, stun_header::ies, if(), stun_header::msglen, stun_header::msgtype, STUN_BINDERR, STUN_BINDREQ, STUN_BINDRESP, stun_get_mapped(), stun_id_cmp(), STUN_MAX_RETRIES, stun_req_id(), stun_send(), and STUN_USERNAME.

Referenced by ast_rtp_stun_request(), ast_stun_handle_packet(), and stun_monitor_request().

Variable Documentation

STANDARD_STUN_PORT

const int STANDARD_STUN_PORT = 3478

static

Definition at line 61 of file stun.h.

Referenced by rtp_reload(), and setup_stunaddr().