Redbooks Paper
Heiko Mueller
William Tworek
Connecting Communities Using the
Lotus Instant Messaging SIP
Gateway
In this Redpaper, we show you how to connect your Sametime® infrastructure to
another Sametime community or SIP-enabled community using the Session
Initiation Protocol (SIP) for easy and secure exchange of instant messages.
The topics in this paper include:
򐂰 What is the Session Initiation Protocol (SIP)
򐂰 Sametime SIP components
򐂰 Setting up the SIP Gateway and Connector
򐂰 Enabling Transport Layer Security (TLS)
򐂰 Using client certificate authentication
򐂰 The end-user experience
򐂰 Example scenarios
© Copyright IBM Corp. 2004. All rights reserved.
ibm.com/redbooks
1
What is the Session Initiation Protocol (SIP)
The Session Initiation Protocol (SIP) is a standard protocol defined by the
Internet Engineering Task Force (IETF). SIP is an application-layer signaling
protocol that handles interactive, multimedia sessions, including presence and
instant messaging. It uses existing transport protocols like TCP to initiate, modify
or terminate a session. SIP is fully bidirectional, and it enables clients and
servers to initiate requests and responses. It is a control protocol that does not
care about content.
SIP for Instant Messaging and Presence Leveraging Extensions (SIMPLE) is an
emerging standard based on the Session Initiation Protocol. SIMPLE is an
extension of SIP that enables awareness and instant messaging. The Sametime
SIP Gateway supports SIMPLE, and if other vendors support SIMPLE, you will
be able to connect to third-party SIP-enabled communities.
Detailed discussions about SIP and SIMPLE are beyond the scope of this
Redpaper. For more information about these protocols, refer to the following
Internet Engineering Task Force (IETF) documents:
򐂰 IP - IETF RFC 3261
򐂰 SIMPLE - draft-ietf-simple-im-01; draft-ietf-simple-presence-06
򐂰 CPIM (Common presence and Instant Messaging) draft-ietf-impp-cpim-msgfmt-06; draft-ietf-cpim-pidf-03
These documents are available at the following site:
http://www.ietf.org
Sametime SIP components
In order to connect your Sametime community to another Sametime or
SIP-enabled community, you need the Sametime SIP Gateway (part of your
Sametime server), as well as the SIP Connector. If you are connecting to another
Sametime community, it will need such components too.
If you have more than one Sametime server in your community and you want to
be able to connect from “everywhere” in your community to other communities,
then you have to configure the Sametime Gateway on every Sametime server in
your community. Otherwise, you can use the installation of SIP capabilities to
separate users that are allowed to communicate to external users.
2
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Sametime SIP Gateway
The Sametime SIP Gateway was introduced in Sametime 3.0 as part of
Sametime Service Pack 1. Since the release of Sametime 3.1, it is now part of
the core Sametime Server (that is, no additional install is needed).
The Sametime SIP Gateway acts as a server application on the Sametime
server. The SIP Gateway processes messages and is responsible for the
translation between the SIP network and the Sametime community.
The configuration of the Gateway component is performed through documents in
the Sametime Configuration Database “stconfig.nsf”.
SIP Gateway functionality
The SIP gateway technology is what ultimately supports the following key
capabilities:
򐂰 Adding users from other SIP-enabled (external) communities
You can add users from other communities to your buddy list by using the
Internet mail address of the person. SIP generally defines users or entities of
other (external) communities by e-mail address.
򐂰 Awareness of online/offline status
You can see the presence awareness of people in the other community, and
people in the other community can the see the awareness of users in your
community.
򐂰 Instant messaging or instant audio/video sessions
You can initiate an instant messaging or audio/video session with a person in
an external community. Only one-to-one sessions are supported; sessions
involving more than two users (that is, n-way sessions) are not supported.
An instant messaging session cannot include audio/video as an additional
meeting activity, or vice versa.
򐂰 Privacy features
You can use the privacy features of Sametime Connect to prevent users in
other communities from seeing your online status.
Restriction: Privacy is not “symmetrical” between communities, as it is in a
single Sametime community. This means that when you use the privacy
features from Sametime, you are still able to see the status of external users.
Similarly, if external users hide their online status, they are still able to detect
your status.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
3
򐂰 Transport encryption
Instant messages can be sent encrypted between different communities
using Transport Layer Security (TLS). However, audio/video streams are not
encrypted.
Sametime SIP Connector
The SIP Connector is a separate component from the SIP Gateway, and it must
be installed on a separate machine. The Connector communicates with the SIP
Gateway through a single SIP connection to the Sametime server that will be
specified during installation of the SIP Connector.
While the SIP Gateway is installed on every Sametime server for which you want
to give users the capability to communicate via SIP, the SIP Connector is
installed on one main “connecting” server only.
A single SIP Connector can support multiple external SIP communities and
Sametime servers. However, you can also set up multiple SIP Connectors in your
community for failover and load balancing.
SIP Connector functionality
The SIP Connector performs the following tasks:
򐂰 It receives outbound SIP data from the local SIP Gateway.
򐂰 It constructs outbound SIP messages.
򐂰 It creates connections to an SIP-enabled component (like another Sametime
community or a third-party SIP proxy server).
򐂰 It receives connection from an SIP-enabled component in another community.
򐂰 It parses inbound SIP messages.
򐂰 It forwards inbound messages to the SIP Gateway on the Sametime server.
Sametime SIP Proxy
The Sametime SIP Proxy is not a “component” of the Sametime solution, but
rather a combination of the Sametime SIP Gateway and the SIP Connector.
Product documentation related to SIP will sometimes refer to this SIP proxy
concept.
The SIP Proxy is responsible for routing and delivering all calls to an
SIP-enabled community. The concept of an “SIP Proxy” is part of the SIP
standard, and it is a term regularly used in the industry around the SIP protocol;
4
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
thus, it is important for readers to understand how Sametime implements this
concept.
Setting up the SIP Gateway and Connector
In order to connect Sametime communities, or to connect your infrastructure to
another SIP-enabled instant messaging environment, your community must
contain at least one SIP Gateway and one SIP Connector.
If you have more than one Sametime server in your community, you must
configure the SIP Gateway on each Sametime server that will participate in the
SIP network.
Planning your infrastructure
When you plan to connect only to other communities within your corporate
network, you can install the SIP Connector on any intranet machine that has
network access to the Sametime SIP Gateway of your community. The SIP
Connector must simply be able to connect to the Sametime server in the
community on TCP/IP port 1516, and connect to the other communities on the
default SIP port of 5060.
However, when you plan to connect to other external instant messaging
networks over the Internet, your SIP Connector must be available beyond your
company’s firewall via the SIP port (5060), and also be able to establish
connections to your Sametime server inside the firewall on port 1516. This will
often be implemented by placing the SIP connector within the DMZ layer of your
organization’s firewall.
Other options affecting your architecture are traffic, availability and failover.
When these are taken into consideration, you are left with several possible
deployment combinations of connectors and gateways. We discuss these in the
following sections.
One SIP Gateway, one SIP Connector
One SIP Gateway and one SIP Connector is the basic installation to enable your
Sametime community to communicate externally.
Several SIP Gateways, one SIP Connector
Several SIP Gateways and one SIP Connector are used if you have more than
one Sametime server in your community.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
5
Several SIP Gateways, several SIP Connectors
When you use more than one SIP Connector, you can configure each connector
to serve an another external community, or you can set up each connector to
equally service all external SIP communities, to support heavy traffic and
failover.
Enabling audio/video session over SIP
When a user in your community invites another user to an instant audio/video
meeting, the meeting is created on a Sametime server in your community. The
call control and signaling aspect of this connection is handled by SIP.
If both communities are configured to support SIP, as described earlier in this
chapter, the user from the other community should be able to participate in the
audio/video meeting. Note, however, that the audio/video streams for the
meeting are sourced from the Multimedia Processor (MMP) on the Sametime
server that is hosting the meeting.
This aspect of audio/video connectivity functions as follows:
򐂰 The Audio/Video streams are transmitted using UDP
The Sametime server Audio/Video Services dynamically select the UDP ports
on which to transmit the audio and video streams. These ports are chosen
from the “Interactive Audio/Video Network - Multimedia Processor (MMP)
UDP port numbers start/end at” settings in the Sametime Administration Tool
on the Sametime server.
򐂰 Blocked UDP connections through network restrictions
If any network between the client and the server blocks UDP traffic, the
audio/video streams cannot be transmitted to the client in the other
community. In this case, the audio and video streams can be tunneled over a
single TCP/IP port.
The administrator can specify the TCP port over which the streams will be
tunneled in the “Interactive Audio/Video Network-TCP tunneling port” (default
8084) setting in the Sametime Administration Tool on the Sametime server.
The port specified as the “TCP tunneling port” must be open through all
networks between the client and the server in order for the client to transmit
and receive TCP-tunneled audio and video streams.
Restriction: If the audio/video streams must be routed through an HTTP or
SOCKS proxy server on any network between the user in the external
community and the Sametime server in your community, the user cannot
participate in an instant audio/video meeting with a user in your community.
6
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Installing the Sametime SIP Connector
The Sametime SIP Connector is available for the Windows® NT/Windows 2000
Server and the IBM® iSeries™ system. This Redpaper covers installation to the
Windows infrastructure only.
You can find the software on the Sametime 3.1 Components Disk (CD2) in the
folder: SIP Connector.
Attention: Do not install the SIP Connector on an existing Sametime server,
because installation will overwrite Sametime server settings. Ultimately, in
such a case neither the SIP Connector nor the Sametime server will work.
System requirements
The system requirements for the SIP Connector are similar to those of a
Sametime server. You need at least the following:
򐂰 Windows NT® 4 SP6a or Windows 200 Server/Adv. Server SP 2
򐂰 Pentium® II 400 Mhz minimum
򐂰 512 MB Ram minimum; 1 GB recommended
򐂰 500 MB free disk space
򐂰 64 MB disk swap space
򐂰 TCP/IP network software installed
Installing the SIP Connector
After you start the setup program, choose your install language and accept the
IBM Licence Agreement.
Also choose the drive and directory where you want to install the software, and
then press Next.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
7
Figure 1 Sametime server address
The window shown in Figure 1 will appear; here you enter the name of the
Sametime server that the SIP Connector will connect to.
The Sametime must have a Sametime SIP Gateway configured and must be
reachable from the Sametime SIP Connector on TCP port 1516.
Click Next>.
8
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Figure 2 Name of the Sametime SIP Connector
The window shown in Figure 2 will appear; here you enter the name of the
Sametime SIP Connector. You can choose whatever name you want, but
normally the DNS hostname is used. Keep this name in mind, because you will
need it again when you configure the Sametime SIP Gateway.
Click Next>.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
9
Figure 3 Summary of install parameters
The window shown in Figure 3 will appear, which contains a summary of the
installation parameters. Review this information for accuracy, then click Next. The
installation process will copy the necessary files to the disk drive.
Click Finish on the window that appears next. At this point, installation of the
Sametime SIP Connector is complete.
After the installation you will find two new Windows services installed: ST
Community Launcher, and ST SIP Connector; refer to Figure 4.
Figure 4 Installed Sametime Services
10
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Tip: To troubleshoot the install, check the files sametime.log and sametime.ini
in the destination location folder.
Verifying install
Immediately after installing, the SIP Connector is not able to run because you
have to configure the Sametime SIP Gateway to allow the SIP Connector to talk
to the Gateway. You can check this on your Sametime server in the Sametime.log
file.
After install, you will find three important files in the installation folder:
Sametime.ini, Sametime.log, and Service.ini. We describe these files in the
following section:
򐂰 Sametime.ini
This file contains the configuration data you entered during install. If needed,
you can change the parameters here and restart the SIP Connector:
[ExternalCommunity]
ConnectorName=itsost4
[Connectivity]
VPS_HOST=itso1.cam.itso.ibm.com
򐂰 Sametime.log
This file contains information about connection to the Sametime SIP Gateway.
If the SIP Connector cannot establish a session to the defined SIP Gateway
running on your Sametime server, it logs that event here, and tries again
every minute.
򐂰 Services.ini
This file contains information about the installed services:
[Services]
service101=ST Community Launch
service102=ST SIP Connector
Configuring the SIP Gateway
In order to configure the Sametime SIP Gateway on your Sametime server, you
have to create or edit documents in the Sametime Configuration Database; see
Figure 5 on page 12.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
11
Note: These configuration steps assume that you are utilizing a Sametime 3.1
infrastructure, or a Sametime 3.0 infrastructure with server pack 1.a installed.
By default, Sametime 3.0 (without the service pack) does not have the SIP
gateway logic included)
Figure 5 Sametime Configuration Database
Open the Sametime Configuration Database stconfig.nsf with your Notes client;
you will reach the screen shown in Figure 6.
(You cannot perform this configuration by using the Sametime Web
Administration User Interface.)
Figure 6 Documents responsible for the SIP Gateway and Connector configuration
12
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
During the configuration, you have to create or edit the following documents:
򐂰
򐂰
򐂰
򐂰
Community Gateway
Extern Community
Community Connector
Community Connectivity
We explain these documents in more detail in the following sections.
The Community Gateway document
Open the Community Gateway document by double-clicking it. If this document
does not exist, create one by clicking Create-CommunityGateway from the
menu bar.
With this document, you can switch on or off the communication to external
communities for the current Sametime server. To enable the SIP Gateway on this
server, you have to set the field Support of external communities to True.
The field Convert ID means that your Sametime SIP Gateway converts your
internal user ID to your Internet e-mail address when communicating with
external communities. This field must be set to True because SIP identifies users
by their e-mail address; see Figure 7.
Important: You must enable e-mail address translation on every Sametime
server in your community, so repeat the preceding steps on every Sametime
server in the community.
Figure 7 Configuring the Community Gateway document
The Extern Community document
The Extern Community document describes the communication parameters to
an external community and security information. There must be one of these
documents for each external SIP community you want to connect to.
Open the Extern Community document you want to edit, or create an additional
one if necessary by clicking Create-Other-ExternCommunity from the menu
bar.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
13
Figure 8 Configuring the Extern Community document
As shown in Figure 8, the document contains the following fields:
򐂰 Community Name
The Descriptive name for the external community (for example, the name of
the organization you want to connect to).
򐂰 Domains
One or more domain names associated with the external community.
򐂰 DNS
The fully-qualified DNS name of the SIP proxy of the external community. If
this field is empty, the SIP Connector performs a DNS lookup and tries to
connect to the specified domains.
򐂰 Port
The default port for SIP Connections is 5060.
򐂰 Encryption (optional)
Data can be sent encrypted to the other community using Transport Layer
Security (TLS). This is discussed later in this Redpaper.
򐂰 Certificate distinguish name (optional)
You can set up client certificate authentication for connections between the
SIP Connectors. This is also discussed later in this paper.
The Community Connector document
The Community Connector document contains information about the SIP
Connector within your community, and configuration parameters of each
connector. There must be one of these documents for each SIP Connector in
your community.
Open the Community Connector document you want to edit, or create an
additional one if necessary by clicking Create-CommunityConnector from the
menu bar; see Figure 9 on page 15.
14
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Figure 9 Configuration of the Community Connector
This document contains the following fields:
򐂰 Connector Name
Enter the name for the connector. It must be the name you gave the SIP
Connector during the installation. For more information, refer to “Installing the
SIP Connector” on page 7.
򐂰 IP
The SIP Connector listens on this IP address for the SIP Connection, or on all
addresses assigned if this field is empty.
򐂰 Port
This is thee port where the SIP Connector listens for SIP connections. The
standard for SIP connection is port 5060.
򐂰 TLS IP (optional)
This is the IP address that the SIP Connector uses for TLS-encrypted
connections.This is discussed later in this paper.
򐂰 TLS Port
This is the port where the SIP Connector listens for TLS-encrypted
Connections. This is discussed later in this paper.
򐂰 Supported Communities
Name(s) of the external communities supported by this SIP Connector. These
communities must be defined by the ExternCommunities documents, as
described in “The Extern Community document” on page 13.
The Community Connectivity document
The Community Connectivity document is not only a configuration document for
the Sametime SIP Gateway—it also contains information and configuration data
regarding community services on the Sametime server.
For security reasons, a Sametime server only allows connections from other
server applications (like a SIP Connector, WebSphere® Portal Server, or
Sametime Everyplace®) if the IP address is known by Sametime.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
15
You tell the Sametime server what other IP addresses it should trust by using the
field Community Trusted IPS. Enter the IP addresses of the SIP Connector(s) in
your environment in this field to allow them to interact with the Sametime server;
see Figure 10.
Figure 10 Configuration of Community connectivity
After you perform all of these steps, your Sametime environment is SIP-enabled
and you will be able to communicate with other users in SIP-enabled
communities, or in Sametime communities that have also set up SIP
communication.
Disabling SIP Gateway functionality
To prevent a user from communicating with users in different communities, you
can disable SIP Gateway functionality. The easiest way to do this is to prevent the
SIP Gateway from making or receiving connections from other communities by
editing the Communication Gateway document on the Sametime server.
Open the Sametime Configuration database stconfig.nsf with your Notes client.
Open the Community Gateway document by double-clicking it. To disable your
Gateway, set the field Support of external communities to False. Save the
document.
Enabling Transport Layer Security (TLS)
Exchanging data with partners and customers is very important today. With SIP
you extend your connectivity with real-time capabilities like instant messaging or
audio/video sessions. Because instant messages can contain very sensitive
information (for example, chat text, e-mail addresses), security is very important
16
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
especially when you connect your Sametime infrastructure over the Internet with
other SIP-enabled communities. To secure your SIP Connections, you can set up
Transport Layer Security (TLS) and Client Certificate Authentication for your
connections.
Important: All procedures in this section must be performed in both your
community and the external community to ensure secured encrypted data
transmission in both directions.
Encrypting SIP traffic
Encrypting the traffic between communities with Transport Layer Security (TLS)
is the highest level of security you can set up on your Sametime SIP Gateway. All
instant messages except audio/video sessions will be encrypted.
To enable your infrastructure to send and receive encrypted messages, you have
to change the configuration of your SIP Gateways and manage and install the
certificates used for the encryption.
Managing certificates
Transport Layer Security uses certificates for authentication and encryption like
the Secure Sockets Layer (SSL) protocol.The certificate management and the
certificates have to be installed and configured to enable the SIP Connector to
secure the connections. Because every community can establish connections,
the SIP Connector is either server or client and needs access to the certificates
in order to operate as client or server in TLS connections.
Configuring the SIP Gateway for TLS
To enable your Sametime SIP Gateway to handle encrypted connections, you
must specify the following:
򐂰 The host name and port for encrypted connections
The TLS port must be defined in two places. One is in the Community
Connector document, where you define on which port your SIP connector will
listen for incoming TLS connections. The other is in the “extern” document,
where you define on which port the external SIP community is listening, and
thus where the SIP connector should attempt to establish a secure
connection on. Both sides must be enabled for full two-way encryption.
򐂰 The encryption mode
As described earlier, you must configure your Sametime SIP Gateway by editing
the Sametime Configuration database “stconfig.nsf” with a Lotus® Notes® client.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
17
Open the Community Connector document. To enable encryption, you have to fill
out the fields TLS IP and TLS Port; refer to Figure 11.
Figure 11 Setting Host name and port for TLS connections
򐂰 TLS IP
This specifies the port on which the SIP Connector listens for encrypted
connections from other communities.
򐂰 TLS Port
This is the port for encrypted connections. The default port is 5061.
Note: If TLS IP and TLS Port are configured, an encrypted connection can be
requested by an external SIPConnector even you do not have enabled
encryption in your “External Community” document. In other words, if your
configuration does not say to communicate via TLS, but the other end
requests TLS, and TLS has been configured on your server, then the
communication will take place encrypted.
After saving this document, open the ExternCommunity document and change
the port to the number where the external community connector listens for TLS
encrypted connections. The default port is 5061; refer to Figure 12.
.
Figure 12 Setting the encryption mode for the Gateway
18
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Finally, you have to set the encryption mode of your Gateway; this defines how
important encryption is to your gateway. You can choose from three options:
򐂰 Enabled
In enabled mode, the SIP Connector first tries to connect to the other
communities on the TLS port specified in the CommunityConnector
document. If it is not possible to connect on this port, the Connector tries to
establish an unencrypted connection on the port configured for that.
򐂰 Mandatory
In mandatory mode, the SIP Connector also tries first to connect to the other
communities on the TLS port specified in the CommunityConnector
document. However, if the encrypted connection fails, there is no fallback to
attempt an unencrypted connection. Therefore, no connection is established.
򐂰 Disabled
In disabled mode, the Sametime SIP Connector attempts unencrypted
connection to the external communities on the port specified during setup of
the gateway. The default port is 5060.
Installing IBM Key Manager IKeyMAN
After the appropriate SIP components have been enabled to utilize TSL
encryption, the TLS encryption keys and so forth must then be configured and
installed on the server so that encryption can actually take place.
In this Redpaper, we describe the usage and configuration of the IBM tools
required to set up TLS in a Microsoft® Windows environment.
In order to manage certificates you first have to install the IBM Key Manager
known as IKeyMan on your SIP Connector machine. Because the Sametime SIP
Connector does not come with an IBM-JRE environment, you first have to make
some configuration changes on your Sametime server and then copy the
IBM-JRE from the Sametime server machine to the SIP Connector machine.
The changes we made can also be used for SSL-enabled LDAP connections on
your Sametime server.
Adding provider to the file java.security
On your Sametime server, open the file java.security in the directory <Sametime
server install directory>\ibm-jre\jre\lib\security.
Add the line security.provider.5=com.ibm.spi.IBMCMSProvider to the file, as
shown in Example 1 on page 20.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
19
Example 1 Adding provider to java.security file
# List of providers and their preference orders (see above):
security.provider.1=com.ibm.jsse.IBMJSSEProvider
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.spi.IBMCMSProvider
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath
Copy directory IBM-JRE from Sametime server to SIP Connector
Copy the directory IBM-JRE and all subdirectories from <Sametime server install
directory>\ibm-jre\ to your SIP Connector machine in the folder where you
installed the SIP Connector, like c:\sip; refer to Figure 13 on page 20.
Delete gskikm.jar from the folder <SIP install
directory>\ibm-jre\jre\lib\ext\gskikm.jar.
Figure 13 Copied IBM-JRE on SIP Connector
Install GSkit
Create a directory GSKit on the SIP Connector machine. Copy the content from
the GSKit directory from Sametime 3.1 Server CD 2 to the directory GSKit on
your SIP Connector.
Open an command window, switch to the GSKit folder, and then type: setup.exe
GSKit c:\sip - s -f1setup.iss. This performs a silent installation of the GSKit
into the SIP install directory, in this case c:\sip.
To verify the installation, check the following:
򐂰 Registry entry HKLM\Software\IBM\GSK6 has been created
򐂰 The directory GSK6 exists in c:\sip\ibm\
Setting the Java™ environment variable
Open System Properties by right-clicking My System on the desktop.
Create a new System Variable under Advanced - Environment Variables.
Add JAVA_HOME with the value c:\<SIP Install PATH>\ibm-jre\jre; refer to
Figure 14 on page 21.
20
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Figure 14 Adding System variables
Creating the key database
The database is used to store the trusted root and server certificates required for
the TLS handshake on your Connector.
Start the IKeyMan program “gsk6ikm.exe” on your machine from <SIP Install
Path>\ibm\gsk6\bin.
From the menu bar, select Key Database File - New. As shown in Figure 15 on
page 22, complete the fields as follows:
򐂰 Key database type
Scroll down and select CMS.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
21
򐂰 File Name:
Enter the file name; it must be key.kdb.
򐂰 Location:
You must enter the installation folder of the SIP Connector; in our case, it
is C:\SIP.
Figure 15 Creating Key database
After that, you have to fill out a form. Type in your password twice and select the
check box Stash the password in a file, then confirm by pressing OK. You will
receive the confirmation shown in Example 16.
Figure 16 Password encryption confirmation
The password is needed if you add or remove certificates, or create certificate
requests.
Choose trusted root certificate
Next, you need to identify the signer certificate you will use as the trusted root
certificate. The database created before contains several signer certificates, by
default. If you prefer to use a different one, you can request another signer
certificate from the Certificate Authority (CA). Follow the instructions given on the
CA’s Web site about how to request and obtain a signer certificate. Then add the
signer certificate to your key database by using the Import feature of the IBM Key
Manager. Figure 17 on page 23 shows an example of included trusted roots.
22
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
In our testing, we used an internal Domino™ as the Certificate Authority. Refer to
the Domino product documentation for details about how to set up Domino as a
Certificate Authority and create signer certificates.
Figure 17 Example of included trusted roots
Request a server certificate
To obtain a certificate from your chosen signer, you have to create a server
certificate request and submit this to the CA. To create a request, switch the Key
database content drop down list to Personal Certificate Requests and click
New. Fill out the form Create New Key and Certificate Request, as shown in
Figure 18 on page 24. You must complete the following fields:
򐂰 Key Label
Enter a name that will identify the certificate inside the IBM Key Manager.
򐂰 Key Size
Switch to 1024 for highest level of encryption
򐂰 Common Name
This must be the fully-qualified DNS name of the machine where your SIP
Connector is installed.
򐂰 Organization
Enter the name of your organization.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
23
򐂰 County
Enter the county in which the server is located.
Figure 18 Server certificate request form
Specify a directory path and file name, and then click OK to save the certificate
request as a text file.
As shown in Figure 19, the open request will be shown in the list of Personal
Certificates Requests.
Figure 19 List of open certificate requests
After creating the request, you have to submit the certificate to the CA. This can
be done by sending the files to the CA or by pasting the content of the request
file to a field on the Web site of the CA. Follow the instructions given by your
24
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
provider regarding how to submit the request and how to retrieve the certificate
after signing.
As mentioned in “Choose trusted root certificate” on page 22, Domino can also
act as a CA. Therefore you can create you own certificates, especially for internal
use, and thereby avoid paying the fee that commercial CAs charge for
certificates. Refer to Domino documentation for details about how to sign
certificate requests with the Domino CA.
Import server certificate into key database
After receiving the signed certificate from the CA, you must import the file into
your key database on your SIP Connector machine. If not already done, switch
the Key database content drop down list to Personal Certificates, and then click
Receive.... Fill out the following fields in the window shown in Figure 20:
򐂰 Data type
Use the default Base64-encoded ASCII data.
򐂰 Certificate file name:
Enter the name of the file that contains your signed certificate.
򐂰 Location
Enter the drive and directory where your certificate is located; in our case, it
is C:\SIP\.
Figure 20 Import a signed server certificate
After importing the certificate, you can see this and all other installed signed
server certificates in the view “Personal Certificates” of your key database, as
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
25
shown in Figure 21.
Figure 21 List of installed server certificates
Click View/edit to see the certificate details; see Figure 22.
Figure 22 Server certificate details
After the certificate has been imported, your SIP Connector can act as server in
a TLS handshake. If your organization or company has more than one SIP
Connector, you need to repeat all these steps for every connector.
26
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
SIP Connector operates as a client in a TLS handshake
In order for your SIP Connector to establish an encrypted connection to another
SIP-enabled instant messaging environment, the connector operates as a client
in a TLS handshake. The SIP “connector” from the other community sends its
SSL server certificate to your connector. The SSL certificate is needed to
negotiate encryption levels and ensure the encryption of the exchanged data.
The server certificate can only be used if your key database contains a “trusted
root” certificate signed by the same CA as the SSL certificate sent to your
connector—or a copy of the signed server certificate sent is by the other
community.
Normally the key databases on both sides will have the necessary trusted root
certificates installed, and therefore no further action needs to be taken. However,
when this is not the case (for example, when Domino is used as the CA), then
you must import a copy of the server certificate of the other community. The Key
Management of the community has to export the server certificate from their key
database and sent it in a secure way (for example, on a floppy disk and using
registered mail) to you. After the import, an encrypted connection can be
established between these two communities.
Using client certificate authentication
Client certificate authentication is an optional procedure that requires an SIP
Connector to authenticate when connecting to another community. Client
certificate authentication verifies the identity of the connecting system through
certificates stored in the key database.
As mentioned, client certificate authentication is optional; note the following:
򐂰 If you choose to receive client certificates from external communities that
connect to your system, you can configure your SIP Connector to request
them.
򐂰 If client certificates are requested by other communities, then you must
configure your SIP Connector to send one out.
Client certificate required by other community
In order for the SIP Connector to send out a client certificate for authentication,
the connector must have access to a signed certificate. This certificate is the
same certificate already generated in earlier procedures for use as a “server”
certificate.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
27
Note: There is no difference between the server certificates previously
described and the client certificates described in this section—it is simply a
matter of at which point the TLS handshake is utilized.
Requiring client certificate from another community
You can set up your SIP Connector to ask for a client certificate when an external
community tries to connect. Client certificate authentication can be configured on
the connection level. That means you can decide, for every external community,
whether client certificate authority is necessary or not.
To enable this functionality, you have to:
򐂰 Edit the Extern Community document
򐂰 Check access to the certificates
The Extern Community document
Open the Sametime Configuration database stconfig.nsf with your Notes client;
refer to Figure 23.
Figure 23 Sametime Configuration Database
Open the Extern Community document that you want to edit. In the field
Certificate distinguish Name, enter the name associated with the client certificate
used by the other community. The name must be entered in canonical format,
like “cn=servername, ou= organizational unit, o=organization”; refer to Figure 24.
If you do not know the name of the certificate, contact the administrator of the
other community.
28
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Figure 24 Configuring the Extern Community document
Note: If you have connections to more than one external community, you have to
do this for every community where you want to enable client certificate authority.
Check access to the necessary certificates
To authenticate external SIP Connectors, you must have a trusted root certificate
signed by the same CA as the client certificate, or a copy of the client certificate
imported in your key database. Refer to “Enabling Transport Layer Security
(TLS)” on page 16 for more information.
The end-user experience
In this section, we describe the overall user experience for users communicating
via SIP Connector. In this environment, Sametime users can communicate with
external users through instant messages and audio/video sessions. However,
other Sametime functionality (for example, sending files) is not supported.
To add external users to your buddy list, you must enter the external e-mail
address of the other person.
Functionality supported with external user
򐂰 Add and remove external users.
򐂰 Privacy settings.
򐂰 Event-based alerts for external users.
򐂰 Send and receive instant messages.
򐂰 Start audio and audio/video session or receive invitations from external.
Functionality not supported with external user
򐂰 External users cannot attend Sametime meetings.
򐂰 No announcements.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
29
򐂰 Full range of online/offline statuses are only supported with external
Sametime communities. For other SIP-enabled communities, only the
online/offline status of a user is supported.
򐂰 No directory services to search for external users.
򐂰 No file transfer.
򐂰 Only one-to-one chat or audio/video session supported.
򐂰 You cannot invite another to a chat or audio/video session with external user.
򐂰 Audio/video session with external users do not include chat.
Adding an external user to a buddy list
To add an external user, select People - Add in your connect client. In the new
dialog window, switch from Sametime to External and enter the e-mail address
and a nickname, if desired. Select the group you want add the user to and click
Add; refer to Figure 25 on page 30.
.
Figure 25 Adding an external user
30
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
The external user and the user’s online status will appear in the group you
selected. External users are marked with a special symbol (the normal icon and
a globe) for presence awareness inside the Sametime Connect client.
The special presence awareness statuses such as “I Am Away” or “Do Not
Disturb Me” will only be exchanged and displayed between two connected
Sametime communities interacting via SIP.
If non-Sametime environments are involved, only the general online or offline
status will be displayed; refer to Figure 26 on page 31.
Figure 26 Buddy list with external participants
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
31
Chat with an external user
To initiate a chat with an external user, follow the same steps as for a Sametime
user. Double-click the user’s name and the chat window appears; refer to
Figure 27 on page 32.
Figure 27 Chat with an external user
As shown in Figure 27, when you exchange instant messages with external
users a globe appears in the left lower corner, indicating that your communication
partner is an external user.
Important: A chat with external users appears unsecured in the chat UI (note
the unlock symbol in the lower right corner), even when you use encryption
with TLS. This is because Sametime does not know whether the external
community encrypts the traffic internally on its end. Therefore, the unsecured
symbol is always been shown.
Example scenarios
In this section, we describe the environment that we developed to demonstrate
SIP connections in a test lab, and what our test infrastructure looked like. We
define three setup scenarios, starting with two SIP communities connected, then
adding another server to this two-community setup, and ending with three SIP
communities connected. For each scenario, we explain what each setup is used
32
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
for, describe who can connect to whom, and tell you how you can extend your
setup and control it.
Important: Our setups only involved Sametime communities.
In cases where other SIP-enabled instant messaging environments are
involved, then other tasks may have to be performed in order to get everything
up and running.
To start, we set up three Sametime communities, as follows:
򐂰 Community A - ITSO-A
A Sametime community with two Sametime servers using Domino Name and
Address book for authenticating users and directory services (although in our
first scenario, we will only use one of the servers in this community).
򐂰 Community B - ITSO-B
A community with only one Sametime server. The server uses LDAP
provided by an IBM Directory Server 4.1 for authentication and directory
services.
򐂰 Community C - ITSO-C
A single server community with Domino directory services like Community A.
Connecting two Sametime communities
Connecting two Sametime communities is the easiest way to expand your
community. As described earlier, you need a Sametime SIP Connector and a
configured Sametime SIP Gateway in each community. Figure 28 illustrates this
two-community architecture.
Community A
"ITSO-A"
Client
A
Port
Port
1533
1516
Sametime 3.1
Server &
SIP-Gateway
Community B
"ITSO-B"
Internet
SIP
Connector
Port 5060
TLS encryption
optional (Port 5061)
Port
Port
1516
1533
SIP
Connector
Sametime 3.1
Server &
SIP-Gateway
Client
A*
Figure 28 Basic infrastructure to connect two Sametime communities
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
33
After connecting, users from Community A, such as Client A, can exchange
instant messages and establish audio/video sessions with users in Community B,
such as Client A*, even if they have different directory services (such as Domino
and LDAP, used in this example setup).
Adding a second Sametime server to your community
In many cases your Sametime community will contain more than one Sametime
server (because of having a huge number of users, or having locations with slow
network connections between them, or in order to separate community services
from meeting services). When you add a Sametime server to your infrastructure
with an SIP connection as described in the previous scenario, there are impacts
for users in both communities, as described here:
򐂰 User on Client A in Community A
This user can see presence awareness from users on other servers in the
user’s community (like users using Client B), and can also see the user using
Client A* from the external Community B (via SIP).
򐂰 User on Client B in Community A
This user can see presence awareness from users on other servers in the
user’s community (like users using Client A). However, this user cannot see
any external users from any other community, because this user’s Sametime
server has no configured Sametime SIP Gateway.
򐂰 User on Client A* in Community B
This user can see the users on both Client A and Client B from the other
community. Thus, this user could send Client B a message, but client B would
be unable to respond.
34
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Community A
"ITSO-A"
Community B
"ITSO-B"
Sametime 3.1
Server &
SIP-Gateway
Port
Port
1533
1516
Client
A
Port 1516
Port
Internet
SIP
Connector
Port 5060
TLS encryption
optional (Port 5061)
Port
Port
1516
1533
SIP
Connector
Sametime 3.1
Server &
SIP-Gateway
Client
A*
1533
Client
B
Sametime 3.1
Server
Figure 29 Sametime community with more than one server
To resolve these issues, you have to create/edit the Communication Gateway
document on the new Sametime server to enable its SIP Gateway.
To do so, open the Sametime Configuration database stconfig.nsf with your Lotus
Notes client; refer to Figure 30.
Figure 30 Sametime Configuration database
Open the Community Gateway document by double-clicking it. If a document
does not yet exist, you can create one by clicking Create-CommunityGateway
from the menu bar.
Set the fields Support external communities and Convert ID to True, and then
save the document; refer to Figure 31.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
35
Figure 31 Configuring the Community Gateway document
Connecting your infrastructure to a second external community
If you open your community services for external communication to partners or
customers, you will often have more than one external community connected. In
our case, this scenario involves expanding our SIP environment to support
another external community.
However, it is important to note that you could use a separate SIP Connector for
this new connection, instead of extending the roles/duties of the existing SIP
connector.
Community A
"ITSO-A"
Client
A
Port
Port
1533
1516
Sametime 3.1
Server &
SIP-Gateway
Community B
"ITSO-B"
Port 5060
TLS encryption
optional (Port 5061)
Internet
SIP
Connector
Port
Port
1533
1516
Sametime 3.1
Server &
SIP-Gateway
SIP
Connector
Figure 32 Connecting three communities
36
Port
1533
SIP
Connector
Community C
"ITSO-C"
Client
A**
Port
1516
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Sametime 3.1
Server &
SIP-Gateway
Client
A*
In this infrastructure, shown in Figure 32, a user on Client A from Community A
can send instant messages to a user on Client A* in Community B and to a user
on Client A** in Community C.
To connect to the Community C over SIP, you have to create/edit the following
documents on your Sametime SIP Gateway.
Extern Community document
Create an Extern Community document for the new community; refer to
Figure 33 on page 37.
Figure 33 Configuring the Extern Community document
Community Connector document
Open the Community Connector document in the database and add the
community you want to connect to the field Supported Communities; refer to
Figure 34.
Figure 34 Add a community to the Community Connector
Save the document. After restarting your Sametime server, you will have
connections to two external SIP-enabled communities: ITSO-A and ITSO-C.
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
37
Summary
In this Redpaper, we introduced the SIP capabilities of Lotus Sametime. We
discussed various deployment options and installation/configuration and general
usage aspects, and provided several sample scenarios for using SIP capabilities.
This paper should help you begin to leverage SIP to extend and connect your
Sametime infrastructure(s).
For details on the latest Lotus Instant Messaging products and capabilities, visit:
http://www-306.ibm.com/software/lotus/collaboration/
To read a Lotus Developer Domain article that covers Sametime SIP capabilities,
visit:
http://www-10.lotus.com/ldd/today.nsf/lookup/SIP
To read the latest Sametime product documentation (including SIP details), visit:
http://www-10.lotus.com/ldd/notesua.nsf/find/sametime
For other IBM Redbooks™ that cover Lotus Instant Messaging technologies,
visit:
http://publib-b.boulder.ibm.com/redbooks.nsf/portals/Lotus
The team that wrote this Redpaper
This Redpaper was produced by a team of specialists from around the world
working at the International Technical Support Organization, Cambridge
Massachusetts.
Heiko Mueller is an IBM PreSales IT Specialist working for IBM Germany. His
expertise is in Lotus collaborative technologies, and he is the Lotus mobile &
wireless technology specialist for the IBM Europe central region sales
organization.
William Tworek is a Project Leader with the International Technical Support
Organization, working out of Westford, Massachusetts. He provides
management and technical leadership for projects that produce IBM Redbooks
on various topics involving IBM and Lotus Software technologies.
38
Connecting Communities Using the Lotus Instant Messaging SIP Gateway
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on
the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.
© Copyright IBM Corp. 2004. All rights reserved.
39
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Domino™
Everyplace®
IBM®
iSeries™
Lotus Notes®
Lotus®
Notes®
Redbooks™
Redbooks (logo)
Sametime®
WebSphere®
™
The following terms are trademarks of other companies:
Intel, Intel Inside (logos), and Pentium are trademarks of Intel Corporation in the United States, other
countries, or both.
Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States,
other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, and service names may be trademarks or service marks of others.
40
Connecting Communities Using the Lotus Instant Messaging SIP Gateway