3 Implementing Instant Messaging Server Security

Overview of Using TLS in Instant Messaging Server

Instant Messaging Server uses a startTLS extension to the TLS 1.0 protocol for client-to-server and server-to-server encrypted communications and for certificate-based authentication between servers.

Communication between multiplexor and server is over an unsecured transport. When you use TLS for client-to-server communication, the multiplexor simply passes the data from the client to the server and back and does not perform any encryption or decryption.

TLS is fully compatible with SSL and includes all necessary SSL functionality. TLS and SSL function as protocol layers beneath the application layers of XMPP and HTTP.

For Java requirements to use TLS with Instant Messaging Server, see the topic on required software in Instant Messaging Server Installation and Configuration Guide.

For information on TLS and StartTLS in XMPP, see Use of TLS in RFC 3920, Extensible Messaging and Presence Protocol: Core, at:

http://www.ietf.org/rfc/rfc3920.txt

For an overview of certificates, SSL, and TLS, see Oracle GlassFish Server Administration Guide. These procedures assume that you are using GlassFish Server to generate certificates.

Setting Up TLS for Instant Messaging Server

Enabling TLS for Instant Messaging Server server-to-server and client-to-server communication requires the following general steps:

1. Creating a Java keystore (JKS) and a private key by using the keytool utility.

   For an overview of the keytool utility, see "Tools for Managing Security" in Sun GlassFish Enterprise Server v2.1.1 Administration Guide. For instructions on generating the JKS by using GlassFish Server, see "Working with Certificates and SSL" in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

2. Using the private key to generate a server certificate for the Instant Messaging server.

   See "Generating a Certificate Using the keytool Utility" in Sun GlassFish Enterprise Server v2.1.1 Administration Guide for instructions.

3. Getting the Instant Messaging server certificate signed by a Certificate Authority (CA).

   See "Signing a Digital Certificate Using the keytool Utility" in Sun GlassFish Enterprise Server v2.1.1 Administration Guide for instructions. Replace GlassFish Server with Instant Messaging Server where applicable.

4. Restarting Instant Messaging Server.

   See Instant Messaging Server System Administrator's Guide for details.

5. Obtaining the CA's root certificate.

   Contact your CA for instructions on obtaining the CA's root certificate.

6. Importing the certificates into the keystore.

   You import the CA root certificate and the signed server certificate into the keystore by using the keytool utility as described in "Using the keytool Utility" in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

7. Activating TLS in the server by setting the appropriate configuration properties.

   See "Activating TLS on Instant Messaging Server" for instructions.

8. For server-to-server communication over TLS, you need to repeat these steps for each server that communicates over TLS. You also do not need to configure the multiplexor for TLS.

9. Configuring the gateway to communicate directly with the Instant Messaging server and not the multiplexor, if you are using the XMPP/HTTP Gateway in your deployment.

Activating TLS on Instant Messaging Server

Before you can activate TLS on the server, you must create a JKS, obtain and install a signed server certificate, and trust the CA's certificate as described in "Setting Up TLS for Instant Messaging Server". You activate TLS on the server when you want to use TLS for server-to-server and/or client-to-server communication.

Table 3-1 lists the configuration properties used to enable TLS in Instant Messaging Server. It also contains the description and the default values for these properties.

Internal (Software) Token:password

API Reference Documentation

The SSOProvider API documentation is provided as part of the Instant Messaging Server installation. You can find the documentation in InstantMessaging_home/html/apidoc, which, by default, is /opt/sun/comms/im/html/apidoc.

How the Custom SSO Module for Instant Messaging Server Works

Instant Messaging Server calls the verify method provided by the custom SSO provider with the uid and token arguments.

The token argument is the password provided by the Instant Messaging client during the SASL PLAIN authentication. For example the client has sent the following:

<body rid='607740' sid='7675823097240743042' xmlns='http://jabber.org/protocol/httpbind' 
key='c654f46426c6d12cf2a0e1a9beb218915e0afd6f'  ><auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'
mechanism='PLAIN'>c2hqb3J0aEBhdS5vcmFjbGUuY29tAHNoam9ydGgAc2VjcmV0dG9rZW4=</auth></body>

c2hqb3J0aEBhdS5vcmFjbGUuY29tAHNoam9ydGgAc2VjcmV0dG9rZW4= is the base64 encoded SASL PLAIN string as per the XEP-0034 standard. This string decodes to:

shj@example.com<NUL>shjorth<NUL>secrettoken

where:

shj@example.com is the authorization identity

shj is the authentication identity

secrettoken is the password (or in this case the SSO token) provided by the IM client

<NUL> is the NUL character

Implementing the Custom SSO Module

Before designing a solution for the custom SSO module, the Instant Messaging Server SSO provider framework needs to be implemented:

• All custom SSO modules must implement SSOProvider interface.

• The SSO verification implementation must provide the domain of the authenticating user if iim.userprops.store is set to ldap.

• The SSO implementation can use any other classes that are required to make the custom SSO module work.

To implement a custom SSO module:

1. Create the custom SSO Java file.

   mkdir -p com/client/sample/
   

2. Use the following sample code to create the file.

   com/client/sample/CustomSSOProvider.java
   import java.util.Map;
   import com.iplanet.im.server.RealmManager;
   import com.iplanet.im.server.LocalUser;
   import com.iplanet.im.server.LDAPUserSettings;
   import com.iplanet.im.common.util.Log;
   
   public class CustomSSOProvider implements SSOProvider {
   
      // This is called for each authentication. It can return true or false.
      public boolean verify(String uid, String token, java.util.Map attributes, java.util.Set attributeNames){
   
        String domain = "your.domain.com";
        Log.debug(String.format("CustomSSO: Trying to authenticate user: %s, token = %s\n", uid, token));
   
        // Replace the following check with your SSO token verification routine
        if (token.equalsIgnoreCase("secrettoken") == false) {
          Log.debug("CustomSSO: 'secrettoken' not provided as password, SSO login attempt failed");
          return false;
        }
   
        // If user properties are stored in LDAP then need to retrieve them
        if (RealmManager.getUserSettingsStorageProvider() instanceof LDAPUserSettings) {
          Log.debug("CustomSSO: iim.userprops.store = \"ldap\"");
   
          try{
            LocalUser u = RealmManager.getUser(uid, domain, true);
   
            // the domain is mandatory if using a hosted domain configuration
            // the boolean third parameter forces an LDAP fetch
            // (disregarding previously cached entries)
            if(u != null){
              for(Object o: attributeNames){
                String s = (String) o;
                Log.debug("CustomSSO: attributeName: " + s);
                Set prop = u.getAttributeValues(s);
                attributes.put(s, prop);
              }
              return true;
            }
          }
          catch(RealmException ex){
            Log.error("CustomSSO: could not load user: " + uid + " in domain: " + domain);
            return false;
          }
        }
        else {
          Log.debug("CustomSSO: iim.userprops.store = \"file\"");
          return true;
        }
        return false;
      }
   
      // This is called each time there's some XMPP activity by the user. The
      // SSO implementation can use this to keep the session from timing out.
      public boolean refresh(String uid) {
         Log.debug("CustomSSO: refresh called " + uid);
         return true;
      }
   
      // This is for any SSO initialization and is called once on server startup
      public void open() throws Exception {
         Log.debug("CustomSSO: open called");
      }
   
      // this is called before the server is shutdown, though its not guaranteed
      public void close() {
         Log.debug("CustomSSO: close called");
      }
   }
   

3. Compile the source.

   Make sure to compile with JDK1.6. This example uses the JDK installed under /usr/jdk/latest on Solaris OS and Instant Messaging Server under /opt/sun/comms/im.

   /usr/jdk/latest/bin/javac -classpath
   /usr/share/lib/xmpp/improvider.jar:/opt/sun/comms/im/lib/xmppd.jar:/opt/sun/com
   ms/im/lib/imcommon.jar:/opt/sun/comms/im/lib/imnet.jar
   com/client/sample/CustomSSOProvider.java
   

4. Create the jar archive from the compiled files.

   /usr/jdk/latest/bin/jar -cvf CustomSSOProvider.jar 
   com/client/sample/CustomSSOProvider.class
   

5. Move the compiled jar file to the Instant Messaging Server library directory.

   chown bin:bin CustomSSOProvider.jar
   cp -p CustomSSOProvider.jar /opt/sun/comms/im/lib
   

6. Add the jar file to the imadmin command.

   cp imadmin imadmin.orig
   

   Edit the imadmin command and add the following to the end of the server_classpath variable setting:

   $PCD/CustomSSOProvider.jar
   

7. Run the imconfutil command with the following properties to enable the provider.

   iim_server.usesso = "1"
   iim_server.ssoprovider = "com.client.sample.CustomSSOProvider"
   

8. Restart the XMPP server.

   cd /opt/sun/comms/im/
   imadmin stop
   imadmin start
   

9. You should now see the following in the xmppd.log file (when debug log-level is enabled in the log4j.conf file) when logging in by using the password secrettoken:

   [13 Sep 2010 08:53:34,857] DEBUG xmppd [Thread-15] CustomSSO: Trying to authenticate user: shjorth, token = secrettoken
   [13 Sep 2010 08:53:34,857] DEBUG xmppd [Thread-15] CustomSSO: iim.userprops.store = "ldap"
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: uid
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: uniquemember
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: givenname
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunPresenceAccessPermitted
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMUserNewsRoster
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMUserConferenceRoster
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: userpassword
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMRoster
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMConferenceRoster
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMNewsRoster
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunIMUserProperties
   [13 Sep 2010 08:53:34,898] DEBUG xmppd [Thread-15] CustomSSO: attributeName: sunPresenceEntityDefaultAccess
   ...
   

Troubleshooting the Custom SSO Module

For Solaris OS installations of Instant Messaging Server, check the following file for errors when starting the Instant Messaging server:

/var/svc/log/application-sunim:default.log

API Reference Documentation

The SASL Provider API documentation is provided as part of the Instant Messaging Server installation. The documentation is located in the InstantMessaging_home/html/apidoc directory.

How the Custom SASL Module for Instant Messaging Server Works

Instant Messaging Server provides a framework for authenticating clients by means of the SASL protocol. SASL provides a generalized method for adding authentication support to any Instant Messaging clients. The protocol event flow is as follows (For more detail refer to XMPP core RFC3920):

The following high-level steps explain how SASL works:

1. The server informs the client of the available authentication mechanisms:

   <features xmlns='http://etherx.jabber.org/streams'>
   <mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
   <mechanism>PLAIN</mechanism>
   <mechanism>CustomSASL</mechanism>
   </mechanisms>
   </features>
   

2. The client selects an authentication mechanism:

   <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl'     mechanism='CustomSASL'/>
   

3. The server sends a nonce as a BASE64 encoded challenge to client:

   <challenge xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>T0E2TUc5dEVRR20yaGg=</challenge>
   

   The decoded challenge is:

   OA6MG9tEQGm2hh 
   

4. The client sends a BASE64 encoded response to the challenge:

   <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
   T0E2TUc5dEVRR20yaGh1c2VyaWQ=
   </response>
   

   The decoded response is

   OA6MG9tEQGm2hhuserid
   

5. The server decodes the userId which is appended with challenge, and validates the user. If the user exists, it informs the client of a successful authentication:

   <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
   

The sample can be used to implement any custom authentication including Single Sign-On. For example, you can use an SSO-based token instead of userID in Step 4.

Implementing the Custom SASL Module

To develop a custom SASL module, you must implement the Instant Messaging Server SASL provider framework:

1. Use the following sample code to develop SampleSASLProviderFactory. The mechanism in the sample is CustomSASL.

   public class SampleSASLProviderFactory implements SASLServerProviderFactory {
       @Override
       public String[] getSupportedMechanisms() {
           return new String[] {"CustomSASL"};
       }
       @Override
       public SASLServerProvider createInstance(String mechanism) {
           return new SampleSASLProvider();
       }
   }
   

2. The SampleSASLProvider implements SASLServerProvider. It checks if the received response contains the nonce sent suffixed with the user, and sends authentication success. The SASL challenge and responses should be modified to suit your use.

   public class SampleSASLProvider implements SASLServerProvider {
       private CollaborationPrincipal user = null;
       private String domain = null;
       private Map authProperties = new HashMap(2);
       private int reqCount;
       private String[] digestSchemas;
       private Realm realm;
       private boolean failure = false;
       private String nonce;
       @Override
       public void init(Map properties) throws SASLProviderException {
           domain = (String)properties.get(SASLServerProvider.DOMAIN);
           // Supported digest schemas.
           digestSchemas = new String[1];
           digestSchemas[0] = "CustomSASL";
       }
       // Called for START - Send a challenge string
       private void handleAuthRequest(SASLData data) throws Exception {
           Long nonceL = new Random().nextLong();
           nonce = String.valueOf(nonceL);
           data.setResponseData(nonce.getBytes("UTF-8"));
           data.setResponseStatus(SASLData.CHALLENGE);
       }
    
       // Called for RESPONSE - Validate response, send success or another challenge here
       private void handleResponse(SASLData data) throws Exception {
           byte [] pktData = data.getRequestData();
           String digestString;
           digestString = new String (pktData, "UTF-8");
           if (digestString.startsWith(nonce)) {
               realm = RealmManager.getRealm();
               String username = digestString.substring(nonce.length());
               user = realm.getPrincipal(realm.getSearchBase(domain), username);
               data.setResponseData(null);
               data.setResponseStatus(SASLData.SUCCESS);
               authProperties.put(USER , user);
               return;
           }
           data.setResponseStatus(SASLData.FAILURE);
           data.setResponseData(null);
           failure = true;
       }
       @Override
       public Map getProperties() throws AuthenticationException {
           return authProperties;
       }
    
       @Override
       public void close() {
           // Do nothing
       }
       // This method gets called for every SASL packet (start/response) received
       @Override
       public void process(SASLData data) throws SASLProviderException {
           if (failure) {
               throw new SASLProviderException("auth failed");
           }
           if (SASLData.FAILURE == data.getRequestStatus() || SASLData.ABORT == data.getRequestStatus() ) {
               data.setResponseStatus(SASLData.ABORT);
               data.setResponseData(null);
               failure = true;
               return;
           }
           if (null == data.getRequestData() ) {
               throw new SASLProviderException("Has no data");
           }
           if ( (reqCount == 0 && SASLData.START != data.getRequestStatus() ) ||
                (reqCount == 1 && SASLData.RESPONSE != data.getRequestStatus()) ||
                (reqCount == 2) ) {
               data.setResponseStatus(SASLData.ABORT);
               data.setResponseData(null);
               failure = true;
               return ;
           }
           try {
               if (SASLData.START == data.getRequestStatus()) {
                   reqCount = 1;
                   handleAuthRequest(data);
               }
    
               if (SASLData.RESPONSE == data.getRequestStatus()) {
                   reqCount = 2;
                   handleResponse(data);
               }
           } catch (Exception e) {
               failure = true;
               throw new SASLProviderException(e);
           }
       }
   }
   

3. Run the following command to compile the Java files:

   javac -cp ".:$SHAREDLIB/imservice.jar:$SHAREDLIB/improvider.jar:$IMBASEDIR/lib/xmppd.jar" SampleSASLProvider.java SampleSASLProviderFactory.java
   

   where:

   • $IMBASEDIR is /opt/sun/comms/im/ in Solaris, and /opt/sun/im/ in Linux

   • $SHAREDLIB is /usr/share/lib in Solaris, and /opt/sun/share/lib in Linux.

4. Create a JAR file out of the generated classes and add it to the server classpath:

   jar -cf /tmp/CustomSASL.jar *.class
   imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop
   iim_server.classpath=/tmp/CustomSASL.jar
   imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_ldap.sasl.mechanism.factories=com.sun.im.provider.sample.SampleSASLProviderFactory
   

5. Restart Instant Messaging Server.

Policy Configuration Properties

Table 3-2 lists Instant Messaging Server policy configuration properties.

Setting the Policy Management Method

The iim.policy.modules configuration property identifies iim_ldap for the access control file method, which is also the default.

To set the policy management method:

1. Use the imconfutil command to set the iim.policy.modules configuration property to iim_ldap (default, the access control file method).

2. Use the imconfutil command to set the iim.userprops.store configuration property to one of the following:

   • ldap (default, for storing user properties in LDAP)

     If you choose ldap, you can run imadmin assign_services to add the required object classes that store user properties to user entries in the directory.

   • file (for storing user properties in files, no longer recommended.)

3. Refresh the configuration.

Managing Policies by Using Access Control Files

By editing access control files you control the following end-user privileges:

• Access to the presence status of the other end users

• Save properties on the server

• Create new conference rooms

By default, end users are provided the privileges to access the presence status of other end users and save properties to the server. For most deployments, default values do not need to be changed.

Although certain privileges can be set globally, the administrator can also define exceptions for these privileges. For example, the administrator can deny certain default privileges to select end users or groups.

In addition, if you are enforcing policy through access control files in your deployment, those files must be the same for all servers in a server pool.

Table 3-3 lists the global access control files for Instant Messaging Server and the privileges these files provide end users.