| Version 5.4
Introduction
Installation
SysAdmin
Network
Objects
Storage
E-mail
Real-Time
Access
Services
Directory
Clusters
Applications
Miscellaneous
Licensing
WebMail
Pronto!
PBX
Overview | POP | IMAP | WebUser | XIMSS | MAPI | AirSync | WebDAV | FTP | TFTP | ACAP
# XIMSS Module Configuring the XIMSS Module XIMSS Connections to Other Modules Flash Security XIMSS Sessions HTTP Binding HTTP Login HTTP Synchronous Communications HTTP Asynchronous Communications Monitoring XIMSS Activity The CommuniGate Pro XIMSS module implements an open XIMSS protocol. This protocol supports advanced clients allowing them to access all Server functions in a secure and effective way. The CommuniGate Pro XIMSS module supports both clear text and secure (SSL/TLS) connections. The the XIMSS Protocol section for more details on the protocol and its features. The CommuniGate Pro XIMSS module requires either a Groupware-type License Key or a special XIMSS License Key. The Server accepts up to 5 concurrent XIMSS sessions without these Keys.

## Configuring the XIMSS Module

Use the WebAdmin Interface to configure the XIMSS module. Open the Access page in the Settings realm:

Processing
Log Level: |  | Channels: |  | Listener

Use the Log setting to specify the type of information the XIMSS module should put in the Server Log. Usually you should use the `Major` (message transfer reports) or `Problems` (message transfer and non-fatal errors) levels. But when you experience problems with the XIMSS module, you may want to set the Log Level setting to `Low-Level` or `All Info`: in this case protocol-level or link-level details will be recorded in the System Log as well. When the problem is solved, set the Log Level setting to its regular value, otherwise your System Log files will grow in size very quickly.

The XIMSS module records in the System Log are marked with the `XIMSSI` tag.

When you specify a non-zero value for the `Maximum Number of Channels` setting, the XIMSS module creates a Listener. The module starts to accept all XIMSS connections that clients establish in order to communicate with your Server. The setting is used to limit the number of simultaneous connections the XIMSS module can accept. If there are too many incoming connections open, the module will reject new connections, and the client should retry later.

By default, the XIMSS module Listener accepts clear text connections on the TCP port 11024. Follow the Listener link to tune the XIMSS Listener.

## XIMSS Connections to Other Modules

XIMSS connections can be made to TCP ports served with other CommuniGate Pro modules. If the first symbol received on a connection made to the HTTP module is the `<` symbol, the HTTP module passes the connection to the XIMSS module.

When a connection is passed:

- the logical job of the passing module completes.
- the logical job of the XIMSS module is created, in the same way when an XIMSS connection is received on a port served with the XIMSS module.
- the XIMSS module restrictions for the total number of XIMSS channels and for the number of channels opened from the same IP address are applied.

When all users initiate XIMSS connections via other Module ports, you can disable the XIMSS Listener by settings all its ports to zero.

## Flash Security

When a Flash client connects to an XMLSocket server (such as the CommuniGate Pro XIMSS module), it can send a special `policy-file-request` request. The XIMSS module replies with an XML document allowing the client to access any port on the Server.

## XIMSS Sessions

When a user is authenticated, the XIMSS module creates a XIMSS session. The current XIMSS module TCP connection can be used to communicate with that session.

A XIMSS session can be created without the XIMSS module, using special requests sent to the HTTP User module. See the XIMSS Protocol section for more details.

The XIMSS session records in the System Log are marked with the `XIMSS` tag.

## HTTP Binding

A client application can access the XIMSS interface via HTTP connections.

A client application should start by sending an HTTP Login request to create a new XIMSS session.

When a XIMSS session is created, the client application can send XIMSS protocol requests to it and receive XIMSS protocol responses from the session using HTTP requests.

Client applications can use `GET` and `POST` HTTP requests.
If a request contains a body, it is assumed to be an XML text, unrelated to the actual value of the Content-Type header field. The XML text must be a `<XIMSS/>` element.
If a request produces a non-empty response body, the body is always an XML text containing one `<XIMSS/>` element, and the response Content-Type header field is `text/xml`.

### HTTP Login

To start a XIMSS session, a client application should send an HTTP request to the CommuniGate Pro HTTPU module using the following URLs:

  `http://domainName[:port]/ximsslogin/`
  or
  `https://domainName[:port]/ximsslogin/`

If the request contains the `userName` parameter, the Server tries to authenticate the specified user (Account):

- If the `password` parameter is present, the regular clear-text method is used.
- If the `nonce` parameter is present, the CRAM-MD5 method is used. The "nonce" parameter value should be a value received as part of a `features` response (see below), it should be a valid "authentication nonce". The request must contain the `authData` parameter containing the base64-encoded CRAM-MD5 "challenge response".
- If the `sessionid` parameter is present, the SessionID method is used.
- If the `errorAsXML` parameter is present and the login operation fails, the error condition is returned not as an HTTP result code with an HTML error page, but as an `<response/>` element with `errorNum` and `errorText` attributes, enclosed into a `<XIMSS/>` element.

If the `userName` parameter is absent, the Server tries to authenticate the request using the TLS Client Certificate (if specified), or using the HTTP authentication methods.
This functionality is the same as the WebUser Interface Automatic Login and Single Sign-on functionality, but the `/ximsslogin/` URL is used.

A request to the `/ximsslogin/` URL can contain a `text/xml` body. In this case, no login operation is performed.
The XML body should contain one `<XIMSS>` element containing zero, one, or several XIMSS Pre-Login operations. The Server sends an HTTP response with XML data. The response is a `<XIMSS>` element containing the requested operations result.

Example:
C:GET /ximsslogin/ HTTP/1.1
Host: myserver.com
Content-Type: text/xml
Content-Length: 42
<XIMSS><listFeatures id="list" /><XIMSS>
S:HTTP/1.1 200 OK
Content-Length: 231
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS><<features id="s" domain="x.domain.dom"><starttls/><sasl>LOGIN</sasl><sasl>PLAIN</sasl><sasl>CRAM-MD5</sasl><sasl>DIGEST-MD5</sasl><sasl>GSSAPI</sasl><nonce>2C3E575E5498CE63574D40F18D00C873</nonce><language>german</language><signup/></features><response id="s"/></XIMSS>

If the user has been successfully authenticated, and the XIMSS session has been created, the HTTP Login response contains the XIMSS `session` message with the session ID string. Note that the `session` message does not contain the `id` attribute.

Example:
C:GET /ximsslogin/?userName=account@domain&password=abcd HTTP/1.1
Host: myserver.com
Content-Length: 0
S:HTTP/1.1 200 OK
Content-Length: 105
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS><session urlID="562-kAI2lxNBR4ApmHg4wiW9" userName="account@domain" realName="J. Smith" /></XIMSS>

Alternative URLs can be used to start a XIMSS session using the TLS Client Certificate, or using the HTTP authentication methods:

  `http://domainName[:port]/auth/ximsslogin/`
  or
  `https://domainName[:port]/auth/ximsslogin/`

This method is useful if an application first retrieves an HTML page or some other document using the `/auth/` realm, forcing the browser to ask the user for credentials, and then the application creates a XIMSS session for the same user, as the browser will resend the same credentials when sending a request to the `/auth/ximsslogin/` URL.

### HTTP Synchronous Communications

A client should send requests to a created XIMSS session use the following Session URL:

  `http://domainName[:port]/Session/sessionID/sync`
  or
  `https://domainName[:port]/Session/sessionID/sync`

where sessionID is the `session` message urlID attribute.

The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests.

The Server returns one <XIMSS /> element in the HTTP response body. This element contains the XIMSS protocol `response` messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests.

Example:
C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/sync HTTP/1.1
Host: myserver.com
Content-Length: nnn
<XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS>
S:HTTP/1.1 200 OK
Content-Length: nnn
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS>

If a XIMSS client works in an unreliable environment, where it may have to resend HTTP requests, then each non-empty HTTP request should contain a `reqSeq` parameter. This parameter value should be increased by 1 for each new HTTP request sent.
If the Server receives an HTTP request with the same `reqSeq` parameter as the previously received and processed HTTP request, then the Server resends the last response (one it has sent to the previous HTTP request wit the same `reqSeq`).
If the Server receives an HTTP request with the `reqSeq` parameter not equal to the `reqSeq` parameter of the previously received request and not equal to the `reqSeq` parameter of the previously received request increased by 1, then the Server returns an error.

A client application can use an "empty request" (an HTTP request without a body) to read asynchronous XIMSS data messages.

When such an empty request is received, the Server checks if there is any pending asynchronous data messages for the specified session. If there is no pending asynchronous data messages, the request is held until either:

- an asynchronous data message is generated for the session; or
- the waiting time is over; or
- a new "empty request" is received; or
- the session is closed.

An empty request can specify the waiting time as the `maxWait` parameter (number of seconds).

If no data messages were retrieved, the Server sends a response containing an empty `<XIMSS/>` element, without any attributes.

If some data messages were retrieved, the Server sends a response (an "asynchronous response") containing one `<XIMSS/>` element, with the `respSeq` attribute. This attribute contains the sequence number for this `<XIMSS/>` response element.

For each session, the Server keeps the last "asynchronous response" composed.

Each empty request should contain a `ackSeq` parameter. It should contain the `respSeq` value of the last received asynchronous response.
If the client has not received any asynchronous response yet, this parameter value must be `0`.

When the Server receives an empty request with the `ackSeq` equal to the `respSeq` value of the kept last composed asynchronous response, it considers that response as "acknowledged", and removes it.

When the Server receives an empty request with the `ackSeq` equal to the `respSeq` value of the last composed asynchronous response minus one (respSeq-1), and it still keeps this composed response, the Server resends that response to the client. As a result, if the client encounters any communication error while doing an "empty request" HTTP transaction, it can resend that empty request.

An empty request without an `ackSeq` parameter acknowledges all "asynchronous responses" composed and kept.

When a server returns an empty `<XIMSS/>` element, the next empty request can contain either no `ackSeq` parameter, or the same `ackSeq` parameter as the previous empty request. Because of this subsequent empty requests may use the same request URL and the same parameters, and the client platform may return the previous cached `<XIMSS/>` element result immediately, without sending the request to the server.
To avoid this problem, include the `getSeq` parameter into each empty request, increasing its value after a successful transaction.

Example:
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&getSeq=0 HTTP/1.1
Host: myserver.com
Content-Length: 0
...optional pause (up to 90 seconds)...
S:HTTP/1.1 200 OK
Content-Length: 10
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS/>
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&getSeq=1 HTTP/1.1
Host: myserver.com
Content-Length: 0
...optional pause (up to 90 seconds)...
S:HTTP/1.1 200 OK
Content-Length: nnn
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS>
response did not reach the client, client is resending the request
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=0&getSeq=1 HTTP/1.1
Host: myserver.com
Content-Length: 0
S:HTTP/1.1 200 OK
Content-Length: nnn
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS respSeq="1"><folderReport folder="INBOX" mode="notify" /></XIMSS>
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=90&ackSeq=1&getSeq=2 HTTP/1.1
Host: myserver.com
Content-Length: 0
...optional pause (up to 90 seconds)...
S:HTTP/1.1 200 OK
Content-Length: 10
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS/>

### HTTP Asynchronous Communications

A client can send requests to a created XIMSS session so that all responses (including the `response` messages and synchronous data messages) are returned only in response to the "empty requests".

  `http://domainName[:port]/Session/sessionID/async`
  or
  `https://domainName[:port]/Session/sessionID/async`

where sessionID is the `session` message urlID attribute.

The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests.

All generated `response` messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests are re-submitted to the XIMSS session as asynchronous messages. The Server returns an empty HTTP response.

Example (single connection, polling):
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&getSeq=0 HTTP/1.1
Host: myserver.com
Content-Length: 0
S:HTTP/1.1 200 OK
Content-Length: 10
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS/>
C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1
Host: myserver.com
Content-Length: nnn
<XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS>
S:HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Content-Type: text/plain;charset=utf-8
Server: CommuniGatePro/5.3
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?maxWait=0&ackSeq=0&getSeq=1 HTTP/1.1
Host: myserver.com
Content-Length: 0
S:HTTP/1.1 200 OK
Content-Length: nnn
Connection: keep-alive
Content-Type: text/xml;charset=utf-8
Server: CommuniGatePro/5.3
<XIMSS respSeq="1"><response id="i1"/><currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/><response id="i2"/></XIMSS>

Example (2 connections, waiting):

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=0&getSeq=0 HTTP/1.1 Host: myserver.com Content-Length: 0 ...waiting... S:HTTP/1.1 200 OK Content-Length: nnn Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3 <XIMSS respSeq="1"> <response id="i1"/> <currentTime id="i2" gmtTime="20070502T083313" localTime="20070502T003313"/> <response id="i2"/> </XIMSS> C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=1&getSeq=1 HTTP/1.1 Host: myserver.com Content-Length: 0 ...waiting... | C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1 Host: myserver.com Content-Length: nnn <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS> S:HTTP/1.1 200 OK Content-Length: 0 Connection: keep-alive Content-Type: text/xml;charset=utf-8 Server: CommuniGatePro/5.3

## Monitoring XIMSS Activity

You can monitor the XIMSS Module activity using the WebAdmin Interface.

Click the Access link in the Monitors realm to open the Access Monitoring page:

|  | 3 of 3 selected

ID | IP Address | Account | Connected | Status | Running
--- | --- | --- | --- | --- | ---
9786 | [216.200.213.116] | user1@domain2.dom | 3min | listing messages | 2sec
9794 | [216.200.213.115] | user2@domain1.dom | 34sec | reading request |
9803 | [216.200.213.115] |  | 2sec | authenticating |

`ID`
  This field contains the XIMSS numeric session ID. In the CommuniGate Pro Log, this session records are marked with the `XIMSS-nnnnn` flag, where nnnnn is the session ID.
`IP Address`
  This field contains the IP address the client has connected from.
`Account`
  This field contains the name of the client Account (after successful authentication).
`Connected`
  This field contains the connection time (time since the client opened this TCP/IP session).
`Status`
  This field contains either the name of the operation in progress or, if there is not pending operation, the current session status (Authenticating, Selected, etc.).
`Running`
  If there is an XIMSS operation in progress, this field contains the time since operation started.

XIMSS activity can be monitored with the CommuniGate Pro Statistic Elements.

CommuniGate® Pro Guide. Copyright © 1998-2012, Stalker Software, Inc.