Home Project Documentation Download Screenshots/videos

Seagull - SIP protocol

SIP protocol details

The implementation of SIP in Seagull conforms to SIP standards

Note

Seagull doesn't currently support "optional" messages. The messages actually exchanged must exactly match the scenario.

Getting started with SIP

First try

So that you can get familiar with Seagull in the context of SIP, here is an example that will launch the following SIP scenario:

 
 |(1) INVITE |
 |--------------------->| 
 |(2) 180 Ringing |
 |<---------------------| 
 |(3) 200 OK |
 |<---------------------| 
 |(4) ACK |
 |--------------------->|
 | |
 |(5) PAUSE |
 | |
 |(6) BYE |
 |--------------------->| 
 |(7) 200 OK |
 |<---------------------|

First try explained using external file

Here is the commented version of the SIP client using a external file to set fields

Scenario. You can also see the client XML scenario. Comments 
<?xml version="1.0" encoding="ISO-8859-1" ?>
<scenario>
<counter>
 <counterdef name="callid-counter" init="0"> </counterdef>
</counter>
<traffic>
 <send channel="channel-1">
 <action>
 
 <inc-counter name="callid-counter"> </inc-counter>
 
 <set-value name="call-id"
 format="$(callid-counter)@255.255.255.255"></set-value>
 
 <restore-from-external field="1" entity="call-id-addr"></restore-from-external>
 
 <store name="local_ip" entity="call-id-addr"></store>
 
 <set-value name="via"
 format="SIP/2.0/UDP 255.255.255.255"></set-value>
 <restore name="local_ip" entity="via-addr"></restore>
 
 <restore-from-external field="4" entity="via-transport"></restore-from-external>
 
 <set-value name="from"
 format="seagull <sip:seagull@255.255.255.255&gt;;tag=1"></set-value>
 
 <restore-from-external field="0" entity="from-name"></restore-from-external>
 
 <store name="local_name" entity="from-name"></store>
 <restore name="local_ip" entity="from-addr"></restore>
 
 <set-value name="to"
 format="sut <sip:service@255.255.255.255:5060&gt;"></set-value>
 
 <restore-from-external field="2" entity="to-name"></restore-from-external>
 <restore-from-external field="3" entity="to-addr"></restore-from-external>
 
 <restore name="local_name" entity="invite-name"></restore>
 <restore name="local_ip" entity="invite-addr"></restore>
 </action>
 <message>
 <! [ CDATA[INVITE sip:schooler@cs.caltech.edu SIP/2.0
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley $lt;sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu>
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE
 Subject: SIP will be discussed, too
 Content-Type: application/sdp
 Content-Length: 187]] >
 <![CDATA[v=0
 o=user1 53655765 2353687637 IN IP4 155.208.221.173
 s=Mbone Audio
 i=Discussion of Mbone Engineering Issues
 e=mbone@somewhere.com
 c=IN IP4 155.208.221.173
 t=0 0
 m=audio 3456 RTP/AVP 0
 a=rtpmap:0 PCMU/8000]] >
 </message>
 <action>
 
 <store name="SID" entity="call-id"></store>
 <store name="VIA" entity="via"></store>
 <store name="FROM" entity="from"></store>
 <store name="TO" entity="to"></store>
 </action>
 </send>
 <receive channel="channel-1">
 <message>
 
 <! [CDATA[SIP/2.0 180 Ringing
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu> ;tag=9883472
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE]] >
 </message>
 </receive>
 <receive channel="channel-1">
 <message>
 
 <! [CDATA[SIP/2.0 200 OK
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu> ;tag=9883472
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE
 Contact: sip:es@jove.cs.caltech.edu]] >
 </message>
 </receive>
<send channel="channel-1">
 <action>
 
 <restore name="SID" entity="call-id"></restore>
 <restore name="VIA" entity="via"></restore>
 <restore name="FROM" entity="from"></restore>
 <restore name="TO" entity="to"></restore>
 
 <restore name="local_name" entity="ack-name"></restore>
 <restore name="local_ip" entity="ack-addr"></restore>
 </action>
 <message>
 
 <! [ CDATA[ACK sip:es@jove.cs.caltech.edu SIP/2.0
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu> ;tag=9883472
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 ACK]] >
 </message>
 </send>
 <send channel="channel-1">
 <action>
 
 <restore name="SID" entity="call-id"></restore>
 <restore name="VIA" entity="via"></restore>
 <restore name="FROM" entity="from"></restore>
 <restore name="TO" entity="to"></restore>
 
 <restore name="local_name" entity="bye-name"></restore>
 <restore name="local_ip" entity="bye-addr"></restore>
 </action> 
 <message>
 
 <! [ CDATA[BYE sip:watson@y.bell-tel.com SIP/2.0
 Via: SIP/2.0/UDP c.bell-tel.com
 From: A. Bell <sip:a.g.bell@bell-tel.com>
 To: T. Watson <sip:t.watson@ieee.org> ;tag=35253448
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 2 BYE]] >
 </message>
 </send>
 <receive channel="channel-1">
 <message>
 
 <! [CDATA[SIP/2.0 200 OK
 Via: SIP/2.0/UDP c.bell-tel.com
 From: A. Bell <sip:a.g.bell@bell-tel.com>
 To: T. Watson <sip:t.watson@ieee.org> ;tag=35253448
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 2 BYE]] >
 </message>
 </receive>
</traffic>
</scenario>

XML header
The call id counter is declared and 
will be incremented for each new call
 
For each new call, increment the call-id and set the call-id field
 
 
 
 
 
Get address from the external file
 
Store it for other fields
 
Set the VIA field
 
 
 
Get protocol from external file
 
Set the From field
 
 
Get Name from external file
 
Store it for other fields 
 
 
Set the To field 
 
Get Name from external file
 
Get address from external file
 
Set the INVITE request address and name
 
 
Header
 
 
 
 
 
 
 
Body
 
 
 
 
 
 
 
 
Store completed fields for future msg
 
 
 
 
 
 
 
 
Header
 
 
 
 
 
 
Header
 
 
 
 
 
 
 
 
 
Restore fields
 
 
 
 
Set name and address in the Ack request
Header
 
 
 
 
 
 
 
 
Restore fields 
 
 
Set name and address in the BYE request
Header
 
 
 
 
 
 
 
 
Header

First try explained with configuration parameters

Here is the commented version of the SIP client using configuration parameters to set fields

In the configuration file, several parameters are added, for example:

<define entity="config-param" name="param_call-id-addr" value="127.0.0.1:5060"></define>
<define entity="config-param" name="param_via" value="SIP/2.0/UDP 127.0.0.1"></define>
<define entity="config-param" name="param_from" value="seagull <sip:seagull@127.0.0.1:5060>;tag=1"></define>
<define entity="config-param" name="param_to" value="sut <sip:service@127.0.0.1:5060>"></define>
They will be used in the sceanrio.

Scenario. You can also see the client XML scenario. Comments 
<?xml version="1.0" encoding="ISO-8859-1" ?>
<scenario>
<counter>
 <counterdef name="callid-counter" init="0"> </counterdef>
</counter>
<traffic>
 <send channel="channel-1">
 <action>
 <!-- For each new call, increment the callid counter -->
 <inc-counter name="callid-counter"> </inc-counter>
 <!-- And set the call-id field -->
 <set-value name="call-id"
 format="$(callid-counter)@127.0.0.1"></set-value>
 
 </action>
 <message>
 <!-- header -->
 <! [ CDATA[INVITE sip:$(param_call-id-addr) SIP/2.0
 Via: $(param_via)
 From: $(param_from)
 To: $(param_to)
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE
 Subject: SIP will be discussed, too
 Content-Type: application/sdp
 Content-Length: 187 ]] >
 <!-- body -->
 <![CDATA[v=0
 o=user1 53655765 2353687637 IN IP4 155.208.221.173
 s=Mbone Audio
 i=Discussion of Mbone Engineering Issues
 e=mbone@somewhere.com
 c=IN IP4 155.208.221.173
 t=0 0
 m=audio 3456 RTP/AVP 0
	 a=rtpmap:0 PCMU/8000]] >
 </message>
 <action>
 <!-- Store completed fields for future msg-->
 <store name="SID" entity="call-id"></store>
 </action>
 </send>
 <receive channel="channel-1">
 <message>
 <!-- header -->
 <! [CDATA[SIP/2.0 180 Ringing
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu> ;tag=9883472
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE]] >
 </message>
 </receive>
 <receive channel="channel-1">
 <message>
 <!-- header -->
 <! [CDATA[SIP/2.0 200 OK
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu> ;tag=9883472
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE
 Contact: sip:es@jove.cs.caltech.edu]] >
 </message>
 </receive>
 <send channel="channel-1">
 <action>
 <!-- restore fields -->
 <restore name="SID" entity="call-id"></restore>
 </action>
 <message>
 <!-- header -->
 <! [ CDATA[ACK sip:$(param_call-id-addr) SIP/2.0
 Via: $(param_via)
 From: $(param_from)
 To: $(param_to)
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 ACK]] >
 </message>
 </send>
 <send channel="channel-1">
 <action>
 <!-- restore fields -->
 <restore name="SID" entity="call-id"></restore>
 </action> <message>
 <!-- header -->
 <! [ CDATA[BYE sip:$(param_call-id-addr) SIP/2.0
 Via: $(param_via)
 From: $(param_from)
 To: $(param_to)
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 2 BYE]] >
 </message>
 </send>
 <receive channel="channel-1">
 <message>
 <!-- header -->
 <! [CDATA[SIP/2.0 200 OK
 Via: SIP/2.0/UDP c.bell-tel.com
 From: A. Bell <sip:a.g.bell@bell-tel.com>
 To: T. Watson <sip:t.watson@ieee.org>;tag=35253448
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 2 BYE]] >
 </message>
 </receive>
</traffic>
</scenario>

XML header
The call id counter is declared and 
will be incremented for each new call
 
First scenario command: send a INVITE message 
Action done before sending message
For each new call, increment the call-id and set the call-id field
 
 
 
 
Set the INVITE request address and name 
Header
Set address from the configuration parameter "param_call-id-addr"
Set Via from the configuration parameter "param_via" 
Set From from the configuration parameter "param_from"
Set To from the configuration parameter "param_to" 
 
 
Body 
Action done after sending message
Store session-id ("Call-id") field for future msg
 
 
 
scenario command: receive a 180 message 
 
 
Header
 
 
 
 
 
 
 
 
scenario command: receive a 200 message 
 
 
Header 
 
scenario command: send a ACK message 
 
Restore session-id in the "Call-id" field
 
 
Header 
 
 
 
 
 
 
 
scenario command: send a BYE message 
 
Restore session-id in the "Call-id" field
 
 
Header 
 
 
 
 
scenario command: receive a 200 message 
 
Header

Miscellaneous considerations

Users must be aware of the fact that Seagull currently works only with "perfect" SIP scenarios. It means that the following messages are not properly handled:

  • Retransmissions (in reception)
  • INFO and NOTIFY messages
  • Optional responses

These points are currently in progress.

SIP authentication

Seagull supports two authentication algorithm: Digest/MD5 ("algorithm="MD5") and Digest/AKA ("algorithm="AKAv1-MD5").
Computing the authorization header is done through the usage of the "method" in a "set-value" action in the scenario.
Depending on the algorithm ("MD5" or "AKAv1-MD5"), different parameters must be passed next to the www-authentication field:

  • Digest/MD5:
    • username: username
    • password: password
    • auth: authentication parameters (example auth=Digest realm="cosims.net", nonce="b8Q2u9ZxyE3VKg6ZD3P07Wo6myth4AAArn7NvQlWWR4=", algorithm=MD5)
    • method: SIP method (example method=INVITE)
    • uri: Uniform Resource Identifier (example uri=sip:127.0.0.1:5061)
  • Digest/AKA:
    • username: username (example : username=joe)
    • aka_k: Permanent secret key (example : aka_k=0x465B5CE8B199B49FAA5F0A2EE238A6BC)
    • aka_op: OPerator variant key (example : aka_op=0xCDC202D5123E20F62B6D676AC72CB318)
    • aka_amf: Authentication Management Field (indicates the algorithm and key in use) (example aka_amf=0xB9B9)
    • auth: authentication parameters (example auth=Digest realm="cosims.net", nonce="b8Q2u9ZxyE3VKg6ZD3P07Wo6myth4AAArn7NvQlWWR4=", algorithm=AKAv1-MD5)
    • method: SIP method (example method=INVITE)
    • uri: Uniform Resource Identifier (example uri=sip:127.0.0.1:5061)

In case of authentication (example for AKA):

  • Add, in the dictionary, the external method:
    • <external-method>
 <defmethod name="authentication"
 param="lib=lib_crypto.so;function=crypto_method">
 </defmethod>
</external-method>
    For now, "crypto_method" is the only available method.

  • and the field "www-authenfication" in the header:
    • <fielddef name="www-authentication"
 format="www-authentication: $(field-value)\r\n">
 <regexp name="auth"
 expr="[wW][wW][wW]-[aA][uU][tT][hH][eE][nN][tT][iI][cC][aA][tT][iI][oO][nN][ ]*:[ ]*([!-}]*).*$"
 nbexpr="2"
 subexpr="1">
 </regexp>
 </fielddef>
  • then in the scenario, set the field "www-authentication" in the pre-action:
    • <set-value name="www-authentication" method="authentication"
 format="username=$(USER_AUTH);aka_op=$(OP-AUTH);aka_k=$(K-AUTH);aka_amf=$(AMF-AUTH);auth=$(AUTH-AUTH);method=$(METHOD-AUTH);uri=$(URI-AUTH)"></set-value>
    The value of "USER_AUTH", OP-AUTH, K-AUTH, AMF-AUTH, AUTH-AUTH, METHOD-AUTH and URI-AUTH can be set with external data from a file with the action "restore-from-external" or from a previous message with the action "store".

Example of scenario which get external data from a file:

 <send channel="channel-1">
 <action>
 <!-- For each new call, increment the callid counter -->
 <inc-counter name="callid-counter"> </inc-counter>
 <set-value name="call-id"
 format="$(callid-counter)@255.255.255.255"></set-value>
 
 <!-- Restore data for authentication -->
 <restore-from-external field="0" name="USER-AUTH"></restore-from-external>
 <restore-from-external field="1" name="AUTH-AUTH"></restore-from-external>
 <restore-from-external field="2" name="METHOD-AUTH"></restore-from-external>
 <restore-from-external field="3" name="URI-AUTH"></restore-from-external>
 <restore-from-external field="4" name="OP-AUTH"></restore-from-external>
 <restore-from-external field="5" name="K-AUTH"></restore-from-external>
 <restore-from-external field="6" name="AMF-AUTH"></restore-from-external>
 <set-value name="www-authentication" method="authentication"
 format="username=$(USER-AUTH);aka_op=$(OP-AUTH);aka_k=$(K-AUTH);aka_amf=$(AMF-AUTH);auth=$(AUTH-AUTH);method=$(METHOD-AUTH);uri=$(URI-AUTH)"></set-value>
 </action>
 <message>
 <!-- header -->
 <! [ CDATA[INVITE sip:schooler@cs.caltech.edu SIP/2.0
 Via: SIP/2.0/UDP north.east.isi.edu
 From: Mark Handley <sip:mjh@isi.edu>
 To: Eve Schooler <sip:schooler@caltech.edu>
 Call-ID: 2963313058@north.east.isi.edu
 CSeq: 1 INVITE
 Subject: SIP will be discussed, too
 Content-Type: application/sdp
 Content-Length: 187]] >
 <!-- body -->
 <![CDATA[v=0
 o=user1 53655765 2353687637 IN IP4 155.208.221.173
 s=Mbone Audio
 i=Discussion of Mbone Engineering Issues
 e=mbone@somewhere.com
 c=IN IP4 155.208.221.173
 t=0 0
 m=audio 3456 RTP/AVP 0
 a=rtpmap:0 PCMU/8000]] >
 </message>
 <action>
 <!-- Store completed fields for future msg-->
 <store name="SID" entity="call-id"></store>
 <store name="VIA" entity="via"></store>
 <store name="FROM" entity="from"></store>
 <store name="TO" entity="to"></store>
 </action>
 </send>

The external data file looks like that:

 "string" ; "string" ; "string" ; "string" ; "string" ; "string" ; "string" ;
 "joe" ; "Digest realm=\"cosims.net\", nonce=\"b8d2v9ZxfE3VHg6ZD3P87Wo1mfth4BBArn7VFQlWWR4=\", algorithm=AKAv1-MD5" ; "INVITE" ; "sip:127.0.0.1:5061" ; "0xCDC2458FEB3E20F62B6D676AC72CB318" ; "0x465B5CE8B199B4BA48D2B72EE238A6BC" ; "0xB9A3" ;
 "xxxxxx" ; "Digest xxxxxxxx" " ; "XXXXXX" ; "xxxxxxxxxxxxxxxxxx" ; "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" ; "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" ; "0xAAAA" ;
 ...
 ...

SIP Correlation example

An example of the correlation feature is proposed in the SIP environment.
Here is the call flow: 

 
 CLIENT SERVER_1 SERVER_2
 |(1) INVITE 
 |--------------------->| 
 |(2) 180 Ringing |
 |<---------------------| 
 |(3) 200 OK |
 |<---------------------| 
 |(4) ACK |
 |--------------------->|
 |
 |(5) INVITE 
 |--------------------->|
 |(6) 180 Ringing |
 |<---------------------| 
 |(7) 200 OK |
 |<---------------------| 
 |(8) ACK |
 |--------------------->|
 |
 (9) INVITE |
 |<--------------------------------------------| 
 |(10) 180 Ringing |
 |<--------------------------------------------| 
 |(11) 200 OK |
 |<--------------------------------------------| 
 |(12) ACK |
 |---------------------------------------------|
 | 
 |(13) PAUSE 
 | 
 |(14) BYE |
 |-------------------------------------------->| 
 |(15) 200 OK |
 |<--------------------------------------------|
 | 
 |(16) BYE |
 |--------------------->| 
 |(17) 200 OK |
 |<---------------------|
The call-id used between the client and the server_1 is defined by the client. The call-id used between the server_1 and the server_2 and between the server_2 and the client is defined by the server_1. The value of this last call-id is sent from the server_1 to the client in the "o" field of the body of the "200 OK" (3) message.
To execute this example, Open three terminal sessions. Terminal 2 will be the server_1, Terminal 3 will be the server_2 and Terminal 1 the client. Examples are located in the "run" directory. So the first thing you need to do is to go in this directory (in both terminal windows): 
 cd run

In Terminal 2 window type:

./start_server_corr_1.ksh

In Terminal 3 window type:

./start_server_corr_2.ksh

In Terminal 1 window type:

./start_client_corr.ksh

AltStyle によって変換されたページ (->オリジナル) /