Understanding SIP Messages in FreeSWITCH: Step-by-Step Guide to Registration and Troubleshooting

By default, when calling an internal user, FreeSWITCH requires the user to be registered to start the call. Otherwise, it will return the error message -ERR USER_NOT_REGISTERED in the SIP messages.

If using tools like Wireshark, you can register with a VOIP endpoint tool locally, and capture SIP messages to observe them.

By capturing packets, you can see the general process as follows:

The content of these four messages resembles the following:

1, First REGISTER

Frame 1: 650 bytes on wire (5200 bits), 650 bytes captured (5200 bits) on interface lo0, id 0
Null/Loopback
Internet Protocol Version 4, Src: 192.168.7.101, Dst: 192.168.7.101
User Datagram Protocol, Src Port: 5060, Dst Port: 5070
Session Initiation Protocol (REGISTER)
    Request-Line: REGISTER sip:192.168.7.101:5070;transport=UDP SIP/2.0
    Message Header
        Via: SIP/2.0/UDP 192.168.7.101:5060;branch=z9hG4bK-d8754z-f407689eddfdf19c-1---d8754z-;rport
            Transport: UDP
            Sent-by Address: 192.168.7.101
            Sent-by port: 5060
            Branch: z9hG4bK-d8754z-f407689eddfdf19c-1---d8754z-
            RPort: rport
        Max-Forwards: 70
        Contact: <sip:[email protected]:5060;rinstance=00eb482b7d4631f5>;transport=UDP
        To: "jimmy"<sip:[email protected]:5070>;transport=UDP
        From: "jimmy"<sip:[email protected]:5070>;transport=UDP;tag=e45e4f61
        Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.
        [Generated Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.]
        CSeq: 1 REGISTER
        Expires: 3600
        Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, NOTIFY, REFER, MESSAGE, OPTIONS, INFO
        User-Agent: Zoiper rev.1809
        Allow-Events: presence
        Content-Length: 0

Initially, no username/password authentication information is included in the registration request.

2. FreeSWITCH returned a 401

Frame 2: 718 bytes on wire (5744 bits), 718 bytes captured (5744 bits) on interface lo0, id 0
Null/Loopback
Internet Protocol Version 4, Src: 192.168.7.101, Dst: 192.168.7.101
User Datagram Protocol, Src Port: 5070, Dst Port: 5060
Session Initiation Protocol (401)
    Status-Line: SIP/2.0 401 Unauthorized
    Message Header
        Via: SIP/2.0/UDP 192.168.7.101:5060;branch=z9hG4bK-d8754z-f407689eddfdf19c-1---d8754z-;rport=5060
            Transport: UDP
            Sent-by Address: 192.168.7.101
            Sent-by port: 5060
            Branch: z9hG4bK-d8754z-f407689eddfdf19c-1---d8754z-
            RPort: 5060
        From: "jimmy" <sip:[email protected]:5070>;transport=UDP;tag=e45e4f61
        To: "jimmy" <sip:[email protected]:5070>;transport=UDP;tag=p8878HBS6XDrB
        Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.
        [Generated Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.]
        CSeq: 1 REGISTER
        User-Agent: FreeSWITCH-mod_sofia/1.10.2-release~64bit
        Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY, PUBLISH, SUBSCRIBE
        Supported: timer, path, replaces
        WWW-Authenticate: Digest realm="192.168.7.101", nonce="84af446e-92ed-418b-96c4-4ad9fee55771", algorithm=MD5, qop="auth"
            Authentication Scheme: Digest
            Realm: "192.168.7.101"
            Nonce Value: "84af446e-92ed-418b-96c4-4ad9fee55771"
            Algorithm: MD5
            QOP: "auth"
        Content-Length: 0

Note line 22, WWW-Authenticate, where the server returns some information needed for authentication: realm/nonce/algorithm/qop, indicating it requires using the MD5 algorithm, prompting the VoIP client to compute a digest based on the server’s response for verification.

3. Second REGISTER

Frame 3: 904 bytes on wire (7232 bits), 904 bytes captured (7232 bits) on interface lo0, id 0
Null/Loopback
Internet Protocol Version 4, Src: 192.168.7.101, Dst: 192.168.7.101
User Datagram Protocol, Src Port: 5060, Dst Port: 5070
Session Initiation Protocol (REGISTER)
    Request-Line: REGISTER sip:192.168.7.101:5070;transport=UDP SIP/2.0
    Message Header
        Via: SIP/2.0/UDP 192.168.7.101:5060;branch=z9hG4bK-d8754z-b6526a3ade0f8d5b-1---d8754z-;rport
            Transport: UDP
            Sent-by Address: 192.168.7.101
            Sent-by port: 5060
            Branch: z9hG4bK-d8754z-b6526a3ade0f8d5b-1---d8754z-
            RPort: rport
        Max-Forwards: 70
        Contact: <sip:[email protected]:5060;rinstance=00eb482b7d4631f5>;transport=UDP
            Contact URI: sip:[email protected]:5060;rinstance=00eb482b7d4631f5
            Contact parameter: transport=UDP
        To: "jimmy"<sip:[email protected]:5070>;transport=UDP
            SIP to display info: "jimmy"
            SIP to address: sip:[email protected]:5070
                SIP to address User Part: 1000
                SIP to address Host Part: 192.168.7.101
                SIP to address Host Port: 5070
        From: "jimmy"<sip:[email protected]:5070>;transport=UDP;tag=e45e4f61
            SIP from display info: "jimmy"
            SIP from address: sip:[email protected]:5070
                SIP from address User Part: 1000
                SIP from address Host Part: 192.168.7.101
                SIP from address Host Port: 5070
            SIP from tag: e45e4f61
        Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.
        [Generated Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.]
        CSeq: 2 REGISTER
        Expires: 3600
        Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, NOTIFY, REFER, MESSAGE, OPTIONS, INFO
        User-Agent: Zoiper rev.1809
         [truncated]Authorization: Digest username="1000",realm="192.168.7.101",nonce="84af446e-92ed-418b-96c4-4ad9fee55771",uri="sip:192.168.7.101:5070;transport=UDP",response="de6d3ab9e4a984d1a7a62d69cd00a31a",cnonce="c7dafa660149cc55",nc=00000001,qop="auth",algorithm="MD5"
            Authentication Scheme: Digest
            Username: "1000"
            Realm: "192.168.7.101"
            Nonce Value: "84af446e-92ed-418b-96c4-4ad9fee55771"
            Authentication URI: "sip:192.168.7.101:5070;transport=UDP"
            Digest Authentication Response: "de6d3ab9e4a984d1a7a62d69cd00a31a"
            CNonce Value: "c7dafa660149cc55"
            Nonce Count: 00000001
            QOP: auth
            Algorithm: MD5
        Allow-Events: presence
        Content-Length: 0

As seen, the second registration includes an Authorization header on line 37 with the username, uri, and the response digest computed based on the server’s request, along with the client’s temporary cnonce value.

Note: Those interested in the digest calculation process can refer to RFC3261 specifications and related articles.

4. FreeSWITCH returned 200

Frame 4: 704 bytes on wire (5632 bits), 704 bytes captured (5632 bits) on interface lo0, id 0
Null/Loopback
Internet Protocol Version 4, Src: 192.168.7.101, Dst: 192.168.7.101
User Datagram Protocol, Src Port: 5070, Dst Port: 5060
Session Initiation Protocol (200)
    Status-Line: SIP/2.0 200 OK
    Message Header
        Via: SIP/2.0/UDP 192.168.7.101:5060;branch=z9hG4bK-d8754z-b6526a3ade0f8d5b-1---d8754z-;rport=5060
            Transport: UDP
            Sent-by Address: 192.168.7.101
            Sent-by port: 5060
            Branch: z9hG4bK-d8754z-b6526a3ade0f8d5b-1---d8754z-
            RPort: 5060
        From: "jimmy" <sip:[email protected]:5070>;transport=UDP;tag=e45e4f61
            SIP from display info: "jimmy"
            SIP from address: sip:[email protected]:5070
                SIP from address User Part: 1000
                SIP from address Host Part: 192.168.7.101
                SIP from address Host Port: 5070
            SIP from tag: e45e4f61
        To: "jimmy" <sip:[email protected]:5070>;transport=UDP;tag=QH20aDvv363aQ
            SIP to display info: "jimmy"
            SIP to address: sip:[email protected]:5070
                SIP to address User Part: 1000
                SIP to address Host Part: 192.168.7.101
                SIP to address Host Port: 5070
            SIP to tag: QH20aDvv363aQ
        Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.
        [Generated Call-ID: ZGEwYTJkMGY1ODQ2M2Q3ZmY3YWQ3M2JkYWVhODMzNGE.]
        CSeq: 2 REGISTER
        Contact: <sip:[email protected]:5060;rinstance=00eb482b7d4631f5>;expires=3600
            Contact URI: sip:[email protected]:5060;rinstance=00eb482b7d4631f5
            Contact parameter: expires=3600
        Date: Sun, 23 May 2021 10:23:16 GMT
        User-Agent: FreeSWITCH-mod_sofia/1.10.2-release~64bit
        Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY, PUBLISH, SUBSCRIBE
        Supported: timer, path, replaces
        Content-Length: 0

After FreeSWITCH receives the submitted authentication information and successfully verifies it, it returns a 200. (Note: If verification fails, it will still return a 401.)

Having roughly understood the registration process, let’s see how SIPp can test this scenario:

First, write the XML file: reg.xml

 1 
 2 
 3 
 4 
 5   
 6     
12       From: [field0] ;tag=[call_number]
13       Call-ID: [call_id]
14       CSeq: 1 REGISTER
15       Expires: 3600
16       User-Agent: SIPp
17       Content-Length: 0
18     ]]>
19   
20 
21  
22  
23 
24 
25     
32       From: [field0] ;tag=[call_number]
33       Call-ID: [call_id]
34       CSeq: 2 REGISTER
35       Expires: 3600
36       User-Agent: SIPp
37       Content-Length: [len]
38     ]]>
39   
40 
41   
42   
43 
44   
45   
46   
47 
48   
49   
50 [field0]@[local_ip]:[local_port]>[field0]@[local_ip]:[local_port]>

The SIP content for the first REGISTER is straightforward to write, but for the second, how to process the final response MD5 value calculation? Do you have to calculate it yourself? Of course not!

SIPp has implemented this digest calculation process internally according to the specification. You just need to reference the “SIP authentication” section in the SIPp documentation, and for the second REGISTER, put the username on a separate line (line 30 in the XML).

Ultimately, execution time for SIPp follows a CSV file like this: reg.csv

SEQUENTIAL
1000;[authentication username=1000 password=1234]
1001;[authentication username=1001 password=1234]
1002;[authentication username=1002 password=1234]
1003;[authentication username=1003 password=1234]
1004;[authentication username=1004 password=1234]
1005;[authentication username=1005 password=1234]
1006;[authentication username=1006 password=1234]
1007;[authentication username=1007 password=1234]
1008;[authentication username=1008 password=1234]
1009;[authentication username=1009 password=1234]
1010;[authentication username=1010 password=1234]
1011;[authentication username=1011 password=1234]
1012;[authentication username=1012 password=1234]
1013;[authentication username=1013 password=1234]
1014;[authentication username=1014 password=1234]
1015;[authentication username=1015 password=1234]
1016;[authentication username=1016 password=1234]
1017;[authentication username=1017 password=1234]
1018;[authentication username=1018 password=1234]
1019;[authentication username=1019 password=1234]

Dynamically extract the username and password from the file, then calculate the digest value and send it to FreeSWITCH.

Run it:

sipp 192.168.7.101:5070 -sf reg.xml -inf reg.csv -d 1000 -trace_err -m 20 -aa

Note: 192.168.7.101:5070 is the IP and port for FreeSWITCH.

If successful, you will see results similar to the above. In FreeSWITCH, you can also verify with commands:

You can see that 20 users have registered successfully. Pick one user, 1001, to view details:

The content in the EXP brackets is the expiration time, Auth-User is the username, and Agent shows it was registered through SIPp.

Finally, a reminder: Users needing registration must be pre-created in FreeSWITCH. If a non-existent user is used, such as 8888:

SEQUENTIAL
8888;[authentication username=8888 password=1234]

During testing, FreeSWITCH will return a 403.

SIP/2.0 403 Forbidden
Via: SIP/2.0/UDP 192.168.7.101:5061;branch=z9hG4bK-48936-1-2
From: 8888 <sip:[email protected]:5061>;tag=1
To: 8888 <sip:[email protected]:5070>;tag=07jyp9tgU8r2c
Call-ID: [email protected]
CSeq: 2 REGISTER
User-Agent: FreeSWITCH-mod_sofia/1.10.2-release~64bit
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY, PUBLISH, SUBSCRIBE
Supported: timer, path, replaces
Content-Length: 0

You can also observe errors from incorrect input on the FreeSWITCH console:

tcp/ipxmlsecurity