Jan
Janak
FhG FOKUS

    		    jan@iptel.org

2003
FhG FOKUS
$Revision: 1.5 $
$Date: 2005/09/04 17:36:28 $

# Registrar Module

## Overview

The module contains REGISTER processing logic.

## NAT Support In Registrar

Registrar and usrloc modules implement NAT extensions that ensure that SIP messages beging sent to registered contacts would use the same socket (with the same IP address and port) on which the REGISTER that registered the contact had been received. REGISTER messages generated by user agents behind NAT ofter open a pinhole in the NAT because REGISTER is usually the first message sent from the user agent to the SIP server. A small example follows.

Let's suppose that we have a single SER instance listening on two ports -- 5060 and 5090. Using a different port seems to be often necessary because of broken SIP ALGs (Application Level Gateways) that are often built into DSL routers or other devices. Such ALGs would mangle SIP requests and responses coming to and from port 5060 and the only option how to avoid such mangling is using a different port number.

Let's suppose that we have two UAs beind NAT, one of them is configured to reach SER on port 5060, the other one is configured to use port 5090 (due to the reasons described above):

                          SER
                      +---------+
    UA1 ---- NAT1 ----| 5060    |
                      |         |
    UA2 ---- NAT2 ----| 5090    |
                      +---------+

Registrar and usrloc would store the public IP of NAT with each registered contact, thus it would know how to reach both user agents.

In addition to the publi IP and port of the NAT device, registrar would also remember the destination IP and port of the REGISTER request (the IP and port used in SER). If registrar did not store this information, it would not know what outbound socket it should use when sending SIP messages to the registered contact. It would use the default port number (often 5060) for such outgoing requests.

When an INVITE for UA1 comes, everything would work because UA1 used port 5060 when registering and that is also the destination port in the pinhole being kept open in NAT1:

                                     SER
                     INVITE UA1  +--------+     INVITE UA1
    UA1 ---- NAT1 <------------- |  5060  | <----------------
                                 |        |
    UA2 ---- NAT2                |  5090  |
                                 +--------+

When an INVITE for UA2 comes, SER would again use port 5060 as the default outgoing source port number, but this time the message will be dropped by NAT2, because the pinhole opened during the registration has 5060 as the destination port number:

                                     SER
                     INVITE UA2  +--------+     INVITE UA2
    UA1 ---- NAT1        +------ |  5060  | <---------------
                         |       |        |
    UA2 ---- NAT2 X <----+       |  5090  |
                                 +--------+

That is the reason why registrar and usrloc also need to remmember the IP and port used on the server side, that information would be used later when forwarding INVITEs:

                                     SER
                                 +--------+     INVITE UA2
    UA1 ---- NAT1                |  5060  | <---------------
                     INVITE UA2  |        |
    UA2 ---- NAT2 <------------- |  5090  |
                                 +--------+

The X next to NAT2 has disappeared in this picture which means that the message will be lucky enough to make it through.

SER would encode this information into a SIP URI when saving contacts in database and later, after restart of SER, this information will be restored. The URI looks like:

    sip:1.2.3.4:5060;dstip=5.6.7.8;dstport=5090

Where the hostname part is the public IP of the NAT, the port (5060) is the port allocated by the NAT, "dstip" parameter is the IP used on SER side and "dstport" parameter is the port number used on SER side during registration. This information is later used to find the correct outgoing socket in SER. If no such socket can be found (it can happen if you reconfigure SER to use different ports or IPs), it will use the default IP/port again.

## Synchronizing UA Internal Clock

Many existing user agents support date and time synchronization from the registrar. Registrar can append "Date" header field to the 200 OK to REGISTER message received from the user agent. User agents that support time synchronization would read the current date and time from the header field and set internal clock to it. For example:

    SIP/2.0 200 OK
    Via: SIP/2.0/UDP 62.240.165.98;branch=z9hG4bK3E66B9EB
    CSeq: 1469 REGISTER
    To: "1 1" <sip:jan@charon.ok2rab.cz>;tag=2bd21cbe8bf183397d829c66d62463e6.0aea
    From: "1 1" <sip:jan@charon.ok2rab.cz>
    Call-ID: 1767561454@62.240.165.98
    Date: Fri, 02 Sep 2005 11:20:12 GMT

You can use `append_time` function from textops module to append the header field to the reply. Put the function before `save("location");` in the configuration file.

### Adding Date header to Replies

    if (uri == myself) {
        if (method == "REGISTER") {
            append_time();
            save("location");
            break;
        };
    };

## Processing +sip.instance parameter

The GRUU extension for SIP (draft-ietf-sip-gruu-04) adds a new parameter to the URI of the Contact header in the REGISTER request to identify a UA instance globaly unique in the world. This is reached by adding a globaly unqiue identifier, the so called sip instace, as a parameter to the Contact URI within all REGISTER requests.

### A Contact header with sip instance parameter

    Contact: <sip:nils@192.168.0.122:2532>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"

By looking at this sip instance parameter the registrar can decide if the incoming request is just an update of an existing Contact URI or if a new Contact URI has to be added to the AOR of this account. Thus even after a reboot of the UA the new REGISTER can be determined the request as an update of an old, already existing entry.

The registrar module now looks for the sip instance parameter in the Contact URI:

- If the sip instance parameter is not present in the URI of the Contact header the algorithm stays the same as like before the GRUU extension. Which means the registrar only compares the SIP URI from the Contact header with the existing URIs for the AOR (account). If exactly the same URI already exists the existing entry will be updated, otherwise the URI will be added to the list.

- If the sip instace parameter is present in the URI of the Contact header it will be first searched for an existing Contact with exactly the same sip instance value. If an URI with exactly the same sip instance value exists already in the database, the existing entry will be replaced with the new value, no matter if they differ or not. If no Contact with this sip instance value exists a new entry for it will be added.

For example the following Contact would replace the Contact value from the example above in the usrloc database because the sip instance value is the same, although the Contact URI differs. Without the sip instance this would have created two entries in the usrloc database.

    Contact: <sip:lando@192.168.0.2:2500>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"

## Dependencies

Registrar module depends on the following SER modules:

- usrloc - User Location Module.

- sl - Stateless Replies.