Ims Communicator User Manual 070418[1]

Portugal Telecom Inovação

IMS-Communicator Documentation Documentation last update: 2007-04-18

IMS-Communicator berlios project page – http://imscommunicator.berlios.de Main Developer: Miguel Freitas >

Introduction................ Introduction................................. .................................. .................................. .................................. .................................. .................................. .................................. .................................1 ................1 Require Requireme ments......................... nts.......................................... .................................. .................................. ................................... ................................... .................................. .................................. ..................... .... 2 IMS-Commu IMS-Communi nicator cator Features.............................. Features............................................... .................................. .................................. .................................. .................................. ........................... ..........2 2 Standards Standards support support list....................... list......................................... ................................... .................................. .................................. .................................. .................................. ........................ ....... 2 Supported Supported features features list list ................................. .................................................. .................................. .................................. .................................. .................................. ..............................2 .............2 IMS-Commu IMS-Communi nicator cator Roadmap Roadmap ................................ ................................................. .................................. ................................... ................................... .................................. ................... 2 Repository............................. Repository.............................................. .................................. .................................. ................................... ................................... .................................. .................................. ..................... .... 3 JMF binari binaries es .................................. ................................................... .................................. .................................. .................................. .................................. .................................. ........................... ..........3 3 Binary Binary releas releases es................ ................................. ................................... ................................... .................................. .................................. .................................. .................................. ........................ ....... 3 Config Configurati uration.............. on............................... .................................. .................................. .................................. .................................. .................................. .................................. .................................4 ................4 How to .................................. ................................................... .................................. .................................. ................................... ................................... .................................. .................................. ..................... .... 6 How to compi compile le .................................. ................................................... .................................. ................................... ................................... .................................. .................................. ..................... .... 6 How to run ................................. .................................................. .................................. .................................. .................................. .................................. .................................. ..............................6 .............6 How to config configure ure the SIP profile.... profile..................... .................................. .................................. .................................. .................................. .................................. ........................... ..........6 6 How to config configure ure a webcam webcam................ ................................. .................................. ................................... ................................... .................................. .................................. ..................... .... 6 How to place place a call call ................................ ................................................. .................................. .................................. ................................... ................................... .................................. ................... 7 How to make make a SIP call call transfe transferr ................................. .................................................. .................................. .................................. .................................. .................................8 ................8 How to enabl enablee the contact-li contact-list st ................................. .................................................. .................................. ................................... ................................... .................................. ................... 8 How to enabl enablee the Peer-to-Peer Peer-to-Peer mode mode ................................. .................................................. .................................. .................................. .................................. ........................ ....... 9 FAQ FAQ ................................ .................................................. ................................... .................................. .................................. .................................. .................................. .................................. ......................... ........ 10 Software Software Licen Licence ce ................................. ................................................... ................................... .................................. .................................. .................................. .................................. ...................... ..... 10

Introduction IMS-Communicator is a SIP softphone based on the old version of the sip-communicator java project ( http://sipcommunicator.org/ ), ), implemented on top of the JAIN-SIP stack ( https://jain-sip.dev.java.net/  https://jain-sip.dev.java.net/ )) and the Java Media Framework API (http://java.sun.com/products/java-media/jmf/  (http://java.sun.com/products/java-media/jmf/ ). ). Some changes have been made to the JAIN-SIP stack to support IMS, such as new SIP headers and SDP functionalities, contribution that have been submitted to the community and is already shipped within the latest JAIN-SIP stack. Originally, the SIP-Communicator client supported normal SIP registration of one public user identity, voice and video session initiation, and some IM functionality, on Windows and Linux. The main IMS User Equipment (UE) procedures were then implemented, as described in the 3GPP specifications TS 24.229, TS 23.228 and others (check http://www.tech-invite.com/  (check  http://www.tech-invite.com/ for for IMS call flows examples). Some of the IMS functionalities implemented include IMS Registration (Authorization, Security Agreement and Subscription to the reg event package), IMS session initiation (PRACK, UPDATE and Precondition Mechanism) and Call

IMS-Commun IMS-Co mmunicator icator – User Manual

1

Transfer. At this point, the IMS-Communicator has several limitations, including the following: − provided support for only one public user identity − user not able to access the IMS network anonymously When placing a call, resources for the media session are considered as available −

Requirements − −

JRE 1.5 (or J2DK 1.5 to compile the project) Java Media Framework (JMF) API (only required when compiling the project) http://java.sun.com/products/java-media/jmf/2.1.1/download.html

−

Apache Ant (to compile the project)

IMS-Communicator Features Standards support list  − − − − − − − − − − − − −

SIP and SDP support (modified JAIN-SIP stack to support IMS) Procedures at the UE (SIP and SDP) – 3GPP TS 24.229 SIP PRACK method (RFC 3262) SIP UPDATE method (RFC 3311) SIP Precondition Mechanism (RFC 3312 + RFC 4032) A SIP Event Package for Registrations (RFC 3680) SIP Security Agreement (RFC 3329 + 3GPP TS 33.203 Annex H) SIP REFER method (RFC 3515) and Session Transfer Procedures (3GPP TS 23.228) SIP Referred-By Mechanism (RFC 3892) 3GPP TS 24.229 – IP multimedia call control protocol based on SIP and SDP HTTP AKA (RFC 3310) HTTP Digest Authentication (RFC 2617) MILENAGE 3GPP Authentication Algorithm (TS 35.205, TS 35.206, TS 35.207, TS 35.208)

Supported features list  − − −

− − −

Setup wizard IMS user Registration and Authentication (AKAv1-MD5) IMS Call Initiation Voice and video calls − JMF 2.1.1 - Supported Formats – http://java.sun.com/products/java-media/jmf/2.1.1/formats.html − SIP Call Transfer (Blind and Consultative Transfer) Dial history Contact list, IM and Presence support

IMS-Communicator Roadmap  − −

Full HTTP AKA support (SQN synchronization) Early Media (RFC 3959, RFC 3960)

IMS-Communicator – User Manual

2

−

IPSec

Repository The IMS-Communicator sources, binary releases and documentation can be obtained from http://imscommunicator.berlios.de. The project can be checked out through anonymous (svnserve) SVN with the following instruction set. •

svn checkout svn://svn.berlios.de/imscommunicator/trunk/ims-communicator

The project can also be checked out through anonymous HTTP with the following instruction set. •

svn checkout http://svn.berlios.de/svnroot/repos/imscommunicator/trunk/ims-communicator

The folder svn.berlios.de/imscommunicator/trunk/ims-communicator contains the Java sources which are bundled within an Eclipse project. It also contains the required libraries (including the modified JAIN-SIP stack), exception made for the JMF binaries which are system dependent and increase heavily the project weight.

JMF binaries  For that reason the JMF binaries are distributed as a separated package, available at the folder < lib> in the repository svn.berlios.de/imscommunicator/trunk/ . They are also available as compressed *.rar files. There’s support for Linux, Windows and Solaris (Solaris JMF package not included – contact us if you are interested). So, download the one you aim and place it in the lib folder inside the IMS-Communicator project.

Binary releases  For your convenience, there are binary releases of the IMS-Communicator available at the folder < releases> in the repository svn.berlios.de/imscommunicator/trunk/ . Extract the package, edit the configuration file and execute the shell script (ims-communicator.bat or ims-communicator.sh).

IMS-Communicator – User Manual

3

Configuration The configuration of the IMS-Communicator is done manually in the ims-communicator.xml file or by the menu Settings > Configure at the UA GUI. Featured next, some explanation of the configuration properties: < n e t . j a v a . s i p . c o mmu n i c a t o r > - g e n e r a l s i p - c o mmu n i c a t o r p r o p e r t i e s − −

FIRST_LAUNCH – “true” for the execution of the configuration wizard in the first launch of the UA ENABLE_SIMPLE – “true” to enable presence with peer contacts

< n e t . j a v a . s i p . c o mmu n i c a t o r . me d i a > - me d i a a n d S DP o p t i o n s −

−

− − − − −

PREFERRED_AUDIO_ENCODING – number of the preferred audio codec, from the audio codecs supported by JMF PREFERRED_VIDEO_ENCODING – number of the preferred video codec, from the video codecs supported by JMF NO_AUDIO_DESCRIPTION_IN_SDP – if audio description should or not be included in the SDP NO_VIDEO_DESCRIPTION_IN_SDP – if video description should or not be included in the SDP MEDIA_SOURCE – path to the media source to be sent AUDIO_PORT – port where to receive incoming audio data VIDEO_PORT – port where to receive incoming video data

< n e t . j a v a . s i p . c o mmu n i c a t o r . s i p > - S I P p r o f i l e c o n f i g u r a t i o n − − − − − − − − − − − −

PUBLIC_ADDRESS – SIP public user identity TRANSPORT – transport protocol used by the client. UDP by default if none configured REGISTRAR_ADDRESS – domain name of the SIP Registrar USER_NAME – user name, used to save the user credentials STACK_PATH – SIP stack, NIST-SIP by default (“ g o v . n i s t ”) PREFERRED_LOCAL_PORT – if none configured or port already in use, other will be generated DISPLAY_NAME – SIP display-name, to be included in the headers From, To and Contact REGISTRAR_TRANSPORT – transport protocol used by the SIP Registrar REGISTRATIONS_EXPIRATION – timeout for the user registration REGISTRAR_PORT – SIP Registrar’s port value DEFAULT_DOMAIN_NAME – IMS home network domain name DEFAULT_AUTHENTICATION_REALM – realm parameter used in the Authentication header

< n e t . j a v a . s i p . c o mmu n i c a t o r . s i p . i ms > - I MS c o n f i g u r a t i o n − − − −

− −

IMS_CLIENT – “true” if IMS procedures to be used at registration and session initiation PRIVATE_ADDRESS – User private address for authentication PREFERRED_ADDRESS – SIP address to be include in the P-Preferred-Identity header PREFERRED_DISPLAY_NAME – optional display name to be include in the P-Preferred-Identity header PRIVACY – value to be included in the Privacy header OPERATOR_ID – operator ID (32 HEX char). Default is all zeros

IMS-Communicator – User Manual

4

−

− −

−

−

−

− − −

−

SECURITY_AGREEMENT – value of the security mechanism parameter. If empty, Security-Client header is not sent SECURITY_ALGORITHM – Algorithm parameter in the Security-Client header if security mechanism equals “ipsec-3gpp”, the following properties are relevant: − SECURITY_ENCRYPT_ALG – Encryption Algorithm parameter in the Security-Client header SECURITY_SPI_C – SPI-Client parameter in the Security-Client header − SECURITY_SPI_S – SPI-Server parameter in the Security-Client header − − SECURITY_PORT_C – Client Port parameter in the Security-Client header − SECURITY_PORT_S – Server Port parameter in the Security-Client header ACCEPT_REFER_WITHOUT_SESSION_ON – accept REFER request from a peer even if a session is not established with that peer PCSCF_DYNAMIC_DISCOVERY – SIP server address and SIP domain discover by stateless DHCPv6 (still work in progress) REG_EVENT_SUBSCRIPTION_TIMEOUT – value to be included in the reg even package SUBSCRIBE Expires header ACCESS_TYPE – user access network type, to be included in the P-Access-Network header DEFAULT_LOCAL_PRECONDITION – precondition mechanism, “e2e” or “sendrecv” VIDEO_BANDWIDTH – bandwidth value to be include in the video media description offer/answer (resource reservation) AUDIO_BANDWIDTH – bandwidth value to be include in the audio media description offer/answer (resource reservation)

< n e t . j a v a . s i p . c o mmu n i c a t o r . s i p . s i mp l e > - S I MP L E c o n f i g u r a t i o n − −

CONTACT_LIST_FILE – name of the file with contact entries LAST_SELECTED_OPEN_STATUS – user presence status at next start -up

< n e t . j a v a . s i p . c o mmu n i c a t o r . g u i > - s o f t p h o n e GUI c o n f i g − −

PHONE_GUI_MODE – true/false flag to show or not the Phone GUI IM_GUI_MODE – true/false flag to show or not the IM and Contact-List GUI

< n e t . j a v a . s i p . c o mmu n i c a t o r . g u i . l o g o > - L o g o a n d I c o n ( f r o m d i r e c t o r y r e s o u r c e / ) − − −

MAIN_LOGO – File name of the image to be set as the phone GUI main logo PHONE_GUI_ICON – true File name of the image to be set as the phone GUI application icon IM_GUI_ICON – File name of the image to be set as the IM/Contact-list GUI application icon

< n e t . j a v a . s i p . c o mmu n i c a t o r . c o mmo n > - n e t wo r k i n t e r f a c e c o n f i g u r a t i o n −

−

PREFERRED_NETWORK_INTERFACE – name of the network interface. OBS: better run the configuration wizard PREFERRED_NETWORK_ADDRESS – network interface address

< j a v a x . s i p > - J AI N- S I P AP I c o n f i g u r a t i o n −

−

IP_ADDRESS – network interface address used for route SIP messages. Make it equal to the value configured in . OBS: better run the configuration wizard OUTBOUND_PROXY – SIP outbound proxy address, in the format IPaddress:port/transport

IMS-Communicator – User Manual

5

How to How to compile  The supplied source code includes an Eclipse project data, so it can be easily imported to the Eclipse workspace. Both the J2DK1.5 and the JMF API must be installed in the system. The Apache Ant is used to build the project. Please make the necessary modifications in the build.xml according to your system configuration. The required libraries for Windows and Linux are also included in the libs/ directory, exception made for the JMF libraries. They are available for each platform at imscommunicator/trunk/lib. Download them to the proper folder in the ims-communicator project (ims-communicator/lib/jmf-win or ims-communicator/lib/jmf-lin).

How to run  Binary releases are available for Windows and Linux. Just configure the ims-communicator.xml file manually (or schedule the execution of the Setup Wizard setting the propert y in ims-communicator.xml

How to enable the contact-list  The IMS-Communicator supports Contact-list, which enables IM and Presence. To show or hide the Contact-list GUI, there’s an option available at Settings > Show/Hide Contact-list. There is also the property which with the “true” value enables the Contact-list GUI by default on the IMS-Communicator start-up.

Image 3 – Enable Contact-list Contacts and Groups can be added. Those actions are accessible thru the mouse’s right button over the entries on the Contact-list GUI.

Image 4 – IMS-Communicator Contact-list GUI



Example of contact-list.xml file

IMS-Communicator – User Manual

8

How to enable the Peer-to-Peer mode  In order to talk directly to another end-point using its IP address, without registering into a SIP server, you would need to make sure that the following properties are empty: * REGISTRAR_ADDRESS * DEFAULT_DOMAIN_NAME * DEFAULT_AUTHENTICATION_REALM * OUTBOUND_PROXY * STUN_SERVER_ADDRESS * STUN_SERVER_PORT * DEMAND_PASSWORD_PRIOR_TO_FIRST_REGISTER – false

How to register with the Open IMS Core  < documentation not yet available >

IMS-Communicator – User Manual

9

FAQ Q – Is there something that I have to do before executing the IMS-Communicator? A – Please run the Setup Wizard (Settings > Run Setup Wizard) and restart your IMS-Communicator client. You can also configure manually by setting the property with the value “true” in the ims-communicator.xml configuration file Q – When the client registration fails, how can I try to register again? A – Please check your SIP profile and restart your IMS-Communicator client. Q – Why don't some modifications seam to make effect when I configure the IMS-Communicator while it is still running. A – Some SIP headers are pre-built and changes to the configuration may not be immediate. Please restart your IMS-Communicator client. Q – I have configured the SIP profile correctly, according to the profile retrieved to me by the IMS network  administrator. Why do I always get 403 Forbidden when I try to register my UA? A – If you are getting 403 Forbidden – HSS Identities don't match, t he problem could be that you haven't configured the correct private user identity in the UA. Please check the ims-communicator.xml property manually or modify it by the menu Settings > Configure > custom properties > sip-ims > Private User Identity. After altering the configurations file, please restart the IMS-Communicator client. Q – Why do I get “403 Forbidden - You must register first with a S-CSCF ” when sending the initial SUBSCRIBE to the reg event package after a successful register? A – This may be an issue due to incomplete network interface configuration. Please run the Setup Wizard (Settings > Run Setup Wizard) and restart your IMS-Communicator client. It as been detected an issue on OpenIMSCore.org concerning the parsing of the P-Preferred-Identity header when it includes the optional display name parameter, which could be causing this 403 Forbidden message. Consider configuring the property with an empty value until this problem isn't fix.

Software Licence This product includes software developed by the Apache Software Foundation ( http://www.apache.org/ ), inherited from the original SIP-Communicator. New libraries and APIs added by PT Inovação are licensed according to the GNU Lesser General Public License.

IMS-Communicator – User Manual

10