NAME

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

SYNOPSIS

    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 );

DESCRIPTION

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.

METHODS

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' => '94.93.237.124',
                            '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.

Server( $MESSAGE, $PORT, $HOST_IP )

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.

OTHER METHODS

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.

true_stun_message( $MESSAGE_TYPE, $MESSAGE_LENGTH, $MAGIC_COOKIE, $TRANSACTION_ID, $ATTRIBUTES, $I_AM_SERVER )

Checks the message for header errors.

%STUN::RFC_5389::attribute_registry

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.

%attribute_sub

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

AUTHOR

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

PREREQUISITES

This module requires the Socket module to be installed.

SEE ALSO

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

COPYRIGHT

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.