++ed by:
Author image Detlef Pilzecker
and 1 contributors


STUN::RFC_5389 - Perl implementation of RFC 5389, Session Traversal Utilities for NAT (STUN)


    use STUN::RFC_5389;

    # create a STUN-message you can then send through your client
    $stun_request = STUN::RFC_5389->Client( { request => 1 } );

    # when you received a message on your server, process it
   # ( $port, $host_ip ) = unpack_sockaddr_in( .... );
    $stun_answer = STUN::RFC_5389->Server( $stun_request, $port, $host_ip );

    # print the error message if the message wasn't RFC 5389 conform
    if ( defined $stun_answer && ! $stun_answer ) {
        print $STUN::RFC_5389::error;
    } else {
        # send the answer back to the client

    # the client can now parse the answer into a hash reference
    $stun_answer_hashref = STUN::RFC_5389->Client( $stun_answer );


This module is used to build, answer and parse STUN (RFC 5389) messages. It can be used by clients and servers.

For now only the main 'required' attributes (MAPPED-ADDRESS and XOR-MAPPED-ADDRESS) and one 'optional' attribute (SOFTWARE) are supported.


Client( { request => 1 | indication => 1 } | $ANSWER )

Creates a new STUN request/indication if the argument is a hash reference. Returns the message in binary format inside a string which can be send to a server.


Parses the $ANSWER (binary STUN-string) and returns a hash reference. The dump of this reference will show you something like this:

    $hash_ref = {
            'message_type'   => '0101',
            'message_length' => 80,
            'magic_cookie'   => '2112a442',
            'transaction_id' => '544fefe8ecdc5732edd4b454',
            'attributes'     => {
                    '0020' => {
                            'address' => '',
                            'port'    => 61497,
                            'family'  => '01'
                    '8022' => {
                            'software' => 'Perl - STUN::RFC_5389 version 0.1 at CPAN, by Detlef Pilzecker.'
                    'XOR-MAPPED-ADDRESS' => $hash_ref->{'attributes'}{'0020'},
                    'SOFTWARE' => $hash_ref->{'attributes'}{'8022'},

If an error was found it will return an empty string and you will find a message in $STUN::RFC_5389::error.


It will parse the $MESSAGE and return a string in bynary format with the (XOR-)MAPPED-ADDRESS which can be send back to the client. $PORT must be a number and $HOST_IP a IPv4 (IPv6 is not supported jet).

If the STUN $MESSAGE Type is 'indication' (0x0011) it will return undef.

If an error was found it will return an empty string and you will find a message in $STUN::RFC_5389::error.


STUN::RFC_5389 also defines some other functions. See source code for more details:

join_attribute( $ATTR_TYPE, $ATTR_VALUE )

Joins type, length and value of the attribute and will fix the length to become a 32-bit boundary length.

parse_attributes( $ATTRIBUTES )

Parses attributes.


Checks the message for header errors.


Is a hash with all RFC 5389 attributes. Its keys are the attribute-hex-values and the values are the human readable attribute names as found in the RFC 5389.


Is a hash with a subroutine (value) for each attribute type (key).


    Detlef Pilzecker, http://search.cpan.org/~deti/, http://www.secure-sip-server.net/


This module requires the Socket module to be installed.


perl(1), Socket, http://tools.ietf.org/html/rfc5389


This module is Copyright (C) 2010 by Detlef Pilzecker.

All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.