[Kamailio-Users] Anyone doing CNAM lookups?

[Brian McCrary]

On Thu, Oct 23, 2008 at 07:02:38AM +0200, Klaus Darilion wrote:

Hello Klaus,

> If you need to trigger SUBSCRIBE you would need the pua module. You 
> would need to write a new module which either sends SUBSCRIBE directly 
> (via tm module) or which links into pua module (which support 
> SUBSCRIBE/NOTIFY in a generic ways).

Thanks for your response!  I was not aware of the pua module.  It looks 
like it would be a good starting point, especially with it's database 
functions.  I think I need to get to work today in setting up a new test 
server so I can play with these new modules and see what changes need to 
be made.

> Do you have a specification of the CNAM lookup (Event: type, payload ...)
> 
> I am not used to CNAM (does not exist in Europe) - how does it work? Do 
> you query the CNAM database during call setup - thus delaying the call 
> setup until you got the answer from the lookup? Or is this an 
> asynchronous mechanism?

Yes, I will post the information I have from Verisign on how it works (a
little lengthy but it does a good job of describing it).  The idea is
indeed to query the database during call setup, and wait for the answer. 
Then the lookup would be forwarded to the SIP phone, ideally in the From
field or P-Asserted Identity giving the called party the name of who is 
calling them.

This info taken from the Verisign manual:

IP CNAM Connectivity
--------------------
VeriSign's IP CNAM connectivity option provides IP access to calling
name databases using the services of the Session Initiation Protocol
(SIP). How IP CNAM Works CNAM Subscribers in the network can subscribe
to CNAM Notifiers' name services on a per call basis. The CNAM Notifiers
can broker those calling name subscriptions to either SS7-resident
databases or IP-resident databases.  The CNAM Notifiers, acting on
behalf of the name databases, can send a notification when those calling
name subscriptions are resolved into the name availability indicator,
calling name, if present, and permanent privacy status associated with
the calling directory number. 

If the name is not to be delivered to the called end-user equipment
because of a 'private' privacy status associated with the name, a 'From'
header display-name parameter with a value of 'private' is sent to the
called end-user equipment. If the name availability indicator reveals
that the name is not available for delivery, a 'From' header
display-name parameter with a value of 'out-of-area/unavailable' is sent
to the called end-user equipment. Otherwise, a 'From' header
display-name parameter containing the derived calling name is sent to
the called end-user equipment. 

Node Behavior
-------------
This section describes how the CNAM subscriber and CNAM Notifier 
functions.

CNAM Subscriber Behavior

To achieve carrier-grade availability and optimal transaction rates, the
CNAM Notifier is optimized to support stateless fetch transactions. When
the subscribe request is transmitted by a CNAM Subscriber to a CNAM
Notifier, this requirement translates to the 'Expires' header having a
value of zero (0) or, alternatively, a subscribe request with no
'Expires' header present, which implies the default value of zero (0) as
defined by the 'calling-name-info'  event package [2]. This use of
subscribe polling reduces the complexity of the calling name event,
limiting the duration of the subscription to a single calling name fetch
and avoiding the necessity to support state related procedures such as
unsubscribing and refreshing subscriptions.

The Request URI of a subscribe request contains enough information to
route the request to the appropriate CNAM Notifier, as listed in the
request routing procedures outlined in SIP. For example, a SIP URI
populated with the fully qualified domain name (FQDN) of the VeriSign
Calling Name Gateway: sip:cnam-gateway.verisign.com. CNAM Subscribers
must populate exactly one 'Event' header in the Subscriber request,
indicating they are subscribing to the calling-name event ('Event:
calling-name').1 Optionally, the CNAM Subscriber may also include within
the 'Event' header an 'id' parameter, which contains an opaque token
that identifies the specific calling name subscription within a SIP
peer-to-peer dialog (e.g. 'Event:calling-name; id=2'). The CNAM Notifier
includes this token, if present, in the corresponding Notify request.

CNAM Notifier Behavior

The CNAM Notifier confirms the Subscribe request with a final response. 
A '200 OK' response indicates that the calling name subscription has
been accepted and that the CNAM Subscriber is authorized to subscribe to
the requested calling name information.

Non-200 class final responses indicate that no subscription has been
created, and no subsequent NOTIFY response is sent. For example, if the
responsible IP-resident or SS7-resident name database is not
out-of-service because of temporary overload conditions, transmission
availability, or maintenance activities. The CNAM Notifier returns a
'503 Service Unavailable' final response, containing a 'Retry-After'
header, which the CNAM Subscriber makes use of to throttle subsequent
traffic to the affected CNAM Notifier.

Once accepted with a '200 OK' response, under no circumstance should a
calling name subscription extend for any longer than the time necessary
for automated processing, such as the time required to query or timeout
waiting for a response from an SS7-resident calling name database.

Upon completion, regardless of the outcome, the CNAM Notifier sends a
Notify request containing a 'Subscription-State' header with a value of
terminated ('Subscription-State: terminated').

The CNAM Notifier must populate the 'Event' header within the Notify
request to indicate a response to the calling name subscription ('Event:
calling-name'). Additionally, if the 'Event' header 'id' parameter was
received in the corresponding Subscribe request, the CNAM Notifier must
echo that value back to the CNAM Subscriber (e.g., 'Event: calling-name;
id=2').

If the subscription request fails due to a processing error (errors
experienced querying SS7-resident name database), the CNAM Notifier
immediately informs the CNAM Subscriber by returning a Notify request,
which includes the 'calling-name-info' event package body indicating an
'out-of-service'  availability. Otherwise the CNAM Notifier must
construct and send a Notify request that includes the calling name
information (name availability, display-name if available, and permanent
privacy status).

Event Package
-------------
Event Package Name

'calling-name' is the token designated as the event identifier for the
calling-name-info event package. Event Packet Parameters This event
package does not define any new 'Event' header parameters.

SUBSCRIBE Body

This mandatory section of the calling-name-info event package defines
the event body expected in Subscriber requests. The Subscribe body
contains the calling-name-request portion of the calling-name-info event
package, indicating address-of-record of callee and optionally the
called party. The calling-name-request syntax is as follows:

calling-name-request = callee CRLF
[ called CRLF ]
callee ="Calling-Party" HCOLON addr-spec
called ="Called-Party" HCOLON addr-spec
addr-spec =SIP URI / SIPS URI / TEL URI
Example:
Calling-Party: sip: 9726840623 at cnam-subscriber;user=phone

NOTIFY Body

This mandatory section of the calling-name-info event package defines
the event body expected in Notify requests. The Notify body contains the
calling-name-response portion of the calling-name-info event, indicating
the availability of the display-name, display-name if present, and the
permanent privacy status. The syntax of the calling-name-response is as
follows:

calling-name-response =calling-name-status CRLF
[calling-name CRLF]
[presentation-indicator CRLF]
calling-name-status ="Calling-Name-Status" HCOLON 
calling-nameavailability
calling-name-availability ="available" / "unavailable" /
"out-of-service"
calling-name ="Called-party" HCOLON name-addr
name-addr =[ display-name ] LAQUOT addr-spec RAQUOT
display-name =* (token LWS) / quoted-string
addr-spec =SIP URI / SIPS URI / TEL URI
presentation-indicator ="Presentation-Indicator" HCOLON "allowed /
"restricted"/ "toggled" / "no indication"

Examples:
Calling-Name-Status: available
Calling-Name: "Joe Smith" <sip:9726840623 at cnam-subscriber.com;user=phone>
Presentation-Indicator: allowed

Message Flow Samples

In the following example, the 200 OK final response messages are omitted 
for brevity.

A1: SUBSCRIBE Message

SUBSCRIBER sip:cnam-notifier.com SIP/2.0
Via: SIP/2.0/UDP cnam-subscriber.com;branch=z9hG4bKnashds8
To: <sip:cnam-notifier.com>
From: <sip:cnam-subscriber.com>;tag=1234
Call-ID: a84b4c76e66710
CSeq: 314159 SUBSCRIBE
Max-Forwards: 10
Contact: <sip:cnam-subscriber.com>
Expires: 0
Event: calling-name; id=2
Content-Type: application/calling-name-info
Content-Length: 54
Calling-Party:sip:9726840623 at cnam-subscriber.com;user=phone

A2: NOTIFY Message

NOTIFY sip:cnam-subcriber.com SIP/2.0
Via: SIP/2.0/UDP cnam-notifier.com;branch=a1hB4bGnashds4
To: <sip:cnam-subscriber.com>;tag=1234
From: <sip:cnam-notifier.com>;tag=5678
Call-ID: a84b4c76e66710
CSeq: 951413 NOTIFY
Max-Forwards: 10
Contact: <sip:cnam-notifier.com>
Event: calling-name; id=2
Subscription-State: terminated
Content-Type: application/calling-name-info
Content-Length:130
Calling-Name-Status: available
Calling-Party: "Joe Smith"
<sip:9726840623 at cnam-subscriber.com;user=phone>
Presentation-Indicator: allowed

Brian