MSRPRelay
---------

Author: Ruud Klaver, Dan Pascu, Saul Ibarra
Home page: http://msrprelay.org


Description
-----------

This software implements the MSRP relay specified by RFC 4976, Relay
Extensions for the Message Session Relay Protocol (MSRP).  Its main role is
to help NAT traversal of Interactive Messaging and File Transfer sessions
for SIP/MSRP endpoints located behind NAT.

The software is licensed according to the GNU General Public License version
2.  See LICENSE file for more details.


Background
-----------

A series of related instant messages between two or more parties can be viewed
as part of a "message session", that is, a conversational exchange of messages
with a definite beginning and end. This is in contrast to individual messages
each sent independently. Messaging schemes that track only individual messages
can be described as "page-mode" messaging, whereas messaging that is part of a
"session" with a definite start and end is called "session-mode" messaging.

Page-mode messaging is enabled in SIP via the SIP MESSAGE method, as defined in
RFC 3428. Session-mode messaging has a number of benefits over page-mode
messaging, however, such as explicit rendezvous, tighter integration with other
media-types, direct client-to-client operation, and brokered privacy and security.

Message Session Relay Protocol (MSRP) is a protocol for transmitting a series
of related instant messages in the context of a session. Message sessions are
treated like any other media stream when set up via a rendezvous or session
creation protocol such as the Session Initiation Protocol (SIP). MSRP Sessions
are defined in RFC 4975.


Features
--------

The software supports different backend modules for SIP account credentials
storage. At the moment, two backends are supported.

* The database backend allows the MSRP Relay to consult a database through
  SQLObject. SQLObject supports several database types, including MySQL and
  SQlite. For a complete listing, see the SQLObject documentation. Out of
  the box, the software is designed to work in combinations with the
  subscriber database used by OpenSIPS (see http://opensips.org).
* The second backend is an in-memory backend, which can be used for testing
  purposes. Username and password combinations can be specified in the
  configuration file.


Multi-domain operation

MSRPRelay is designed to operate in a multi-domain setup. The domains relate
to the SIP domains served by a SIP Proxy/Registrar (e.g.  example.com).

In this setup MSRPRelay runs on a host that is referenced by a DNS A record
(load balancing between several MSRP relays can be achieved by having this A
record refer to more than one IP address).  As an example this would be
"msrprelay.example.com".  MSRPRelay has one TLS certificate/key pair
containing this hostname in the subject alternative name.

For each SIP domain it serves, a DNS SRV record is provisioned. This could be
for example: "_msrps._tcp.msrprelay.org -> msrprelay.example.com:2855".

The client that wishes to reserve a session at a MSRPRelay active within its
SIP domain then resolves the SRV record for its domain, connects to the
relay using TLS and sends an AUTH request with its SIP domain as MSRP URI in
the To-Path header, like such:" msrps://msrprelay.org;tcp".

The MSRP relay then uses the host part of this MSRP URI as domain to
authenticate the user in.

To facilitate testing and remove the need to provision SRV records, taking the
authentication domain from the To-Path MSRP URI can be disabled by manually
specifying the domain in the configuration file. In this case the
authenticating client should put the actual hostname of the MSRPRelay into
the To-Path MSRP URI of an AUTH request. Note that this implies single domain
operation.

Multiple relays per domain

For allowing multiple relays for each domain you must either:

1. Create multiple SRV DNS records pointing to multiple hostnames or

2. Create one SRV record that point to one hostname and add multiple A
   records for that hostname pointing to multiple IP addesses.  When doing
   so it is important that each relay is configured with a hostname that is
   resolvable in the DNS to his own IP address.


Session management

The MSRPRelay was specifically designed to support end-to-end congestion
control for MSRP sessions, in order to support high volume data transfers,
such as file transfers.  For this reason, session sharing between
connections cannot be used and each TCP/TLS connection supports only one
session.

This means that the client will need to open a new connection for each session
before doing an AUTH. Also the MSRP will initiate every time a new connection
to other endpoints so that congestion control can be performed on a session
basis.


Installation             
------------             

See INSTALL file.


Support
-------

The project is developed and supported by AG Projects. The support is
provided on a best-effort basis. "best-effort" means that we try to solve
the bugs you report or help fix your problems as soon as we can, subject to
available resources.

To request support you must use the mailing list available at

http://lists.ag-projects.com/mailman/listinfo/sipbeyondvoip

For commercial support contact AG Projects http://ag-projects.com


Credits
-------

The development of MSRP relay has been sponsored by  NLnet foundation
http://nlnet.nl