Copyright (C) 2003 Metalink LTD
Author: Rodionov Sergey (seger@metalinkltd.com)
This program is distributed under terms of GPL (see LICENSE)

sipbomber - tool for testing SIP-protocol implementation (RFC3261).
Current version can check only server implementation - UAS
(UAS are proxies, user agent servers, redirect servers, and registrars). 

This test use data files from 
http://www.ee.oulu.fi/research/ouspg/protos/testing/c07/sip

                   0. Installation

This program was tested under Redhat9 only.
To compile type "make".
You need correct QT installation (I.e. QTDIR environment variable must be
present in system).
Run "sipb_main".
    
                   I. Send-Recv Tests
          
	  1. Parameters (Overview of general parameters)

sip server - ip or hostname of sip-server (any UAS)

udp port   - server udp port

tcp port   - server tcp port

transport  - type of transport. you can choose
             UDP        - udp transport
	     TCP        - tcp transport. We send and recive use the same 
	                  tcp-connection
	     TCP(broken) -tcp transport. We send and recive use the different
	                  tcp-connection (after send we broke first connection)
	     ANY        - we random choose transport

==========	     
reparse rand param - in almost all tests we create packet from BNF grammar.
                      This parameter mean maximal quantity
		      of not mandate element in BNF-rule. If you want to
		      create large packets get this parameter bigger.

n-send  - quantity of reruns of test.

n-resend - quantity of resend particular packet, if we not receive anything 
            after this packet.

resend timeout - Time in millisecond which we wait of receive packet
                  before send next packet (or resend this packet).
=========

username, user host name, password - this parameters are used to create valid
                                      request.
	     
reset grammar - With this parameter you can reset some BNF rules. For example, 
   it can be used to make packet more simple (by default we 
   reset LWS=1*WSP and WSP=SP in init gramatic LWS  =  [*WSP CRLF] 1*WSP
   and SWS  =  [LWS]) ( for example you can make LWS=1*SP )
   
max content len - We can add random content to some packets. This parameter 
    controls maximal length of this content.

                            2. Tests
			   			   
For all tests we describe single iteration of test 
(n_send parameter mean number of such iteration).


OPTIONS_*  tests can be used for test any type of servers
REGISTER_* tests can be used for test registrat implementation
INVITE_*   tests can be used for test "sip-server" (registrar + proxy)
CERT_TEST  test can be used for test any servers that work with INVITE.


------- OPTIONS_valid ---------

 Behaviour:
     1. send valid OPTIONS request.
       packet may can be two general types:
         - Max-Forwards>0 and addressed to Server
	 - Max-Forwards=0 and addressed to anybody
     2. wait response.
     
-------- OPTIONS_bad1 ----------

 additional parameters: 
 "max change len" and "number of change" 

 Behaviour:
     1. create valid OPTIONS request.
     2. make random change in this request . We randomly change 
     "number of change" parts of packet. Parameter "max change len"
     describe maximal length of this change.
     3. send this packet
     4. wait responce.

-------- OPTIONS_req --------
 
 Behaviour:
     1. Create valid OPTIONS request but add Require field with 
       some random options-tag. 
     2. Send this packet
     3. wait responce (server must send 420 responce).

------- OPTIONS_totag ------

  Behaviour:
     1. Create valid OPTIONS request, but add To-tag (we create packet inside
        non-existent dialog)
     2. Send this packet
     3. wait responce (server must send 481 responce).
  
------- REGISTER_valid -------
 
 Behaviour:
     1. Create valid REGISTER request (for it we use "username" and "userhost
        name"). We create REGISTER with single Contact
     2. Send this packet
     3. Wait responce. If we receive challenge for authorization 
        (401 responce), create valid REGISTER with credentials
	and send it (after it wait next responce)

------- REGISTER_mcont --------

Behaviour:
  similar of REGISTER_valid but may create two Contact in REGISTER.

------- REGISTER_cseq --------
     1. Create first  REGISTER request with first Contact
     2. Send this packet
     3. Wait responce. If receive 401 -> make authorization

     4. Create second REGISTER request with second Contact.
        But we can change CSeq (+ or -) And can change Call-ID
     5. Send this packet.
     6. Wait responce. If receive 401 -> make authorization
     (then analyze last packet: we check server's work with Cseq and Call-ID, 
      rfc3261 10.3 for detail)
    note: if server ignore second packet it's error (even CSeq in second
    packet equal or less CSeq in first packet , And Call-ID the same)!

------- REGISTER_del --------
  Behaviour:
    1. Create first REGISTER request.
    2. Send this packet.
    3. Wait responce. If receive 401 -> make authorization.
   
    4. Create and send REGISTER with request to delete record (we can
       send expires=0 or Contact=* and Expires field = 0).
    5. Wait responce. If receive 401 -> make authorization

------- REGISTER_mcdel --------
 (multi contact delete)
  Behaviour:
    similar to REGISTER_del, but we can send packet with two or more
    Contact (and can delete all or particular Contact)

------ REGISTER_expir ---------
  additional parameters: expires
  Behaviour:
    1. Create first REGISTER request (and set expires parameter of Contact 
       to expires).
    2. Send this packet.
    3. Wait responce. If receive 401 -> make authorization
    
    4. Sleep for expires*2 seconds!
    5. Create REGISTER with empty Contact (for check our Contact)
    6. Wait responce. If receive 401 -> make authorization

  Comments:
    - Very RECOMMENDED to try run this test with expires=1.
    -> test check implementation of "403" Interval To Brief responce

-------- REGISTER_mcexpir ---------
  
  Behaviour similar to REGISTER_expir but we can send request with more than
  one Contact...

------ INVITE_sv_caller and INVITE_sv_callee ---------
  INVITE simple valid test.
  IMPORTANT: for use you SHOULD run both test in parallel.

  additional parameters:
    username  - name of caller user
    username2 - name of callee user
    password  - password of username
    password2 - password of username2
    pause     - pause between REGISTER and INVITE
    Note: user host name -- MUST be real hostname (Where you run sipbomber). 
        Because we make REGISTER with this hostname (and server send INVITE
	to this hostname)
	
 INVITE_sv_caller Behaviour:
  1. Make REGISTER (sip:username@user_host_name:<port for recv>)
     a.) Send REGISTER
     b.) Wait responce. If receive 401 -> make authorization
  2. Make pause (in millisecond)
  2.1 Create INVITE packet.
  3. Wait responce. If receive 407 -> make authorization (PROXY AUTHORIZATION
     IS STILL NOT IMPLEMENTED!)
  4. If receive 1xx --> wait next packet.
  
  INVITE_sv_callee Behaviour:
    1. Make REGISTER (sip:username2@user_host_name:<port for recv>)
         a.) Send REGISTER
	 b.) Wait responce. If receive 401 -> make authorization
    2. Wait request (we wait INVITE from INVITE_sv_caller)
    3. May be send provisional response (150)
    4. Send 486 or 200 response
 
--------- CERT_TEST -------------
 read http://www.ee.oulu.fi/research/ouspg/protos/testing/c07/sip for detail
 this test is implementation with test-suit data from this test.

 Before run this test you may copy testcases directory from c07 packet to ./ 
 directory (or change "testcases dir" parameter then run test)

 additional parameters:
 "CERT From"  - to replace <From>
 "CERT From-Address" - to replace <From-Address>
 "CERT From-IP" - to replace <From-IP>
 "CERT To"      - to replace <To>
 "Teardown list"- list of teardown methods
 "testcases dir"
 "teardown timeout" - (in millisecond)
 "t-t timeout"      - (in millisecond)
 "test timeout"     - (in millisecond)
 
 Behaviour:
 1. Read list of testcases from "testcases dir"
 2. Make each test:
   --read INVITE packet from test.
   --make replace for all known tag (<From> <From-Address> <From-IP> <TO>
                        <Local-Port> <CSeq> <Call-ID>)
   --send packet 
   --wait "teardown timeout" (may be receive something)
   --read Teardown packet from test.
   --for each method from "Teardown list" create Teardown packet 
     (make replace for all known tag + <Teardown-Method>)
     and send it.
  -- after each teardown packet we wait "t-t timeout" milliseconds (may be
     receive something)
  -- wait "test timeout". End, run next text.

