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,,


This module requires the Socket module to be installed.


perl(1), Socket,


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.