MSRP Relay Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. hash_size (int)
              1.3.2. cleanup_interval (int)
              1.3.3. auth_route (str)
              1.3.4. username_var (string)
              1.3.5. realm_var (string)
              1.3.6. password_var (string)
              1.3.7. calculate_ha1 (integer)
              1.3.8. socket_route (str)
              1.3.9. dst_schema_var (string)
              1.3.10. dst_host_var (string)
              1.3.11. auth_realm (string)
              1.3.12. auth_expires (int)
              1.3.13. auth_min_expires (int)
              1.3.14. auth_max_expires (int)
              1.3.15. nonce_expire (integer)
              1.3.16. my_uri (string)

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set server_hsize parameter
   1.2. Set cleanup_interval parameter
   1.3. Set auth_route parameter
   1.4. username_var parameter usage
   1.5. realm_var parameter usage
   1.6. password_var parameter usage
   1.7. calculate_ha1 parameter usage
   1.8. Set socket_route parameter
   1.9. auth_realm parameter usage
   1.10. Set server_hsize parameter
   1.11. Set auth_min_expires parameter
   1.12. Set auth_max_expires parameter
   1.13. nonce_expire parameter example
   1.14. my_uri parameter usage

Chapter 1. Admin Guide

1.1. Overview

   This modules implements a Relay for the MSRP protocol,
   according to the specifications of RFC 4976. Once loaded, the
   module will automatically forward messages and manage MSRP
   sessions for the MSRP listeners defined in the script.

   For authenticating MSRP clients, a dedicated script route is
   run in order to check the Digest credentials via
   pseudo-variables.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * proto_msrp

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * openssl or libssl
     * openssl-dev or libssl-dev

1.3. Exported Parameters

1.3.1. hash_size (int)

   The size of the hash table that stores the MSRP sessions. It is
   the 2 logarithmic value of the real size.

   Default value is “10” (1024 records).

   Example 1.1. Set server_hsize parameter
...
modparam("msrp_relay", "hash_size", 10)
...

1.3.2. cleanup_interval (int)

   The interval between full iterations of the sessions table in
   order to clean up expired MSRP sessions. Note that a session
   will be kept in memory as long as the Expires value provided in
   the 200 OK response to the AUTH request indicates.

   Default value is “60”.

   Example 1.2. Set cleanup_interval parameter
...
modparam("msrp_relay", "cleanup_interval", 30)
...

1.3.3. auth_route (str)

   The name of the script route to be called when authorizing MSRP
   clients (receiving an AUTH request with an Authorization
   header). Here you should provide the appropriate password (or
   pre-calculated HA1 string) for the credentials via the
   password_var pseudo-variable, in order for the relay to check
   the client response.

   No default value; this parameter is mandatory.

   Example 1.3. Set auth_route parameter
...
modparam("msrp_relay", "auth_route", "auth")
...

1.3.4. username_var (string)

   This name of the pseudo-variable that holds the authentication
   username.

   Default value is “$var(username)”.

   Example 1.4. username_var parameter usage
modparam("msrp_relay", "username_var", "$var(msrp_auth_user)")

1.3.5. realm_var (string)

   This name of the pseudo-variable that hols the authentication
   Realm.

   Default value is “$var(realm)”.

   Example 1.5. realm_var parameter usage
modparam("msrp_relay", "realm_var", "$var(msrp_auth_realm)")

1.3.6. password_var (string)

   This name of the pseudo-variable that should be set in the
   auth_route script route in order to check the client response
   when authenticating. The value to be set can be either the
   plaintext password or pre-calculated HA1 string, based on the
   parameter.

   Default value is “$var(password)”.

   Example 1.6. password_var parameter usage
modparam("msrp_relay", "password_var", "$var(msrp_auth_password)")

1.3.7. calculate_ha1 (integer)

   This parameter configures whether the value of the password_var
   pseudo-variable should be treated as a plaintext password or a
   pre-calculated HA1 string.

   Default value of this parameter is 0 (HA1 string).

   Example 1.7. calculate_ha1 parameter usage
modparam("msrp_relay", "calculate_ha1", 1)

1.3.8. socket_route (str)

   The optional name of the script route to be called when start
   relaying a new MSRP session (upon the first SEND). The purpose
   of this route is to allow you to select the appropriate
   outbound socket to be be used for sending out the MSRP request.

   Inside the route, the following information from the received
   request will be exposed:
     * source network information via the $si, $sp, $sP and
       $socket_in variables.
     * destination URL schema via the dst_schema_var variable
     * destination URL host via the dst_host_var variable

   In this route you should optionally set the desired MSRP(S)
   outbound socket via the $socket_out variable. If none is set,
   the inbound interface will also be used as outbound if the
   schema (MSRP versus MSRPS) is the same. If the schema changes,
   the first socket (matching the out schema) will be used.

   Default value is “NULL” (none).

   Example 1.8. Set socket_route parameter
...
modparam("msrp_relay", "socket_route", "msrp_routing")

route[msrp_routing] {
        xlog("MSRP request comming from $si:$sp on $socket_in socket\n")
;
        xlog("trying to go to $var(dst_schema)://$var(dst_host)\n");

        $socket_out = "msrp:1.2.3.4:9999";
}
...

1.3.9. dst_schema_var (string)

   This name of the variable to provide the schema ("msrp" or
   "msrps") of the destination URL in the socket route. See more
   on param_socket_route parameter.

   Default value is “$var(dst_schema)”.

1.3.10. dst_host_var (string)

   This name of the variable to provide the host of the
   destination URL in the socket route. See more on
   param_socket_route parameter.

   Default value is “$var(dst_host)”.

1.3.11. auth_realm (string)

   The realm to be provided in the WWW-Authenticate header when
   the relay automatically challanges an MSRP client.

   If this parameter is not set, the realm chose by the relay is
   the domain part of the top MSRP URI in the To-Path header of
   the AUTH request.

   Example 1.9. auth_realm parameter usage
modparam("msrp_relay", "auth_realm", "opensips.org")

1.3.12. auth_expires (int)

   The Expires header value to be provided in the 200 OK response
   to an AUTH request, if the client does not explicitly request
   one. This represents how long the MSRP URI provided by the
   relay in the Use-Path header is valid.

   Default value is “1800” (1024 records).

   Example 1.10. Set server_hsize parameter
...
modparam("msrp_relay", "auth_expires", 600)
...

1.3.13. auth_min_expires (int)

   The minimum value accepted by the relay in the Expires header,
   if the client provides it in the AUTH request. If the requested
   value is lower that this parameter, the relay will include a
   Min-Expires header with the configured value, in the 423
   Interval Out-of-Bounds response.

   If not set, the relay will accept any value.

   Example 1.11. Set auth_min_expires parameter
...
modparam("msrp_relay", "auth_min_expires", 60)
...

1.3.14. auth_max_expires (int)

   The maximum value accepted by the relay in the Expires header,
   if the client provides it in the AUTH request. If the requested
   value is higher that this parameter, the relay will include a
   Max-Expires header with the configured value, in the 423
   Interval Out-of-Bounds response.

   If not set, the relay will accept any value.

   Example 1.12. Set auth_max_expires parameter
...
modparam("msrp_relay", "auth_max_expires", 60)
...

1.3.15. nonce_expire (integer)

   Nonces have limited lifetime. After a given period of time
   nonces will be considered invalid. This is to protect replay
   attacks. Credentials containing a stale nonce will be not
   authorized, but the user agent will be challenged again. This
   time the challenge will contain stale parameter which will
   indicate to the client that it doesn't have to disturb user by
   asking for username and password, it can recalculate
   credentials using existing username and password.

   The value is in seconds and default value is 30 seconds.

   Example 1.13. nonce_expire parameter example
modparam("msrp_relay", "nonce_expire", 15)   # Set nonce_expire to 15s

1.3.16. my_uri (string)

   MSRP URI of this relay, that will be matched against the first
   URI in the To-Path header of any request or response received.
   Messages that are not addressed to this relay will be dropped.

   The MSRP URI provided by the relay in the Use-Path header, will
   be chosen based on the URI in the To-Path header of the AUTH
   request.

   This parameter can be set multiple times

   If the port is not set explicitly, the default value of 2855
   wil be assumed. The session-id part of the URI should not be
   set

   Example 1.14. my_uri parameter usage
modparam("msrp_relay", "my_uri", "msrp://opensips.org:2855;tcp")

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Vlad Patrascu (@rvlad-patrascu) 22 7 1646 16
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 7 4 200 20
   3. Maksym Sobolyev (@sobomax) 4 2 3 3

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Maksym Sobolyev (@sobomax)          Feb 2023 - Nov 2023
   2. Vlad Patrascu (@rvlad-patrascu)     Mar 2022 - May 2023
   3. Bogdan-Andrei Iancu (@bogdan-iancu) Apr 2022 - May 2023

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad
   Patrascu (@rvlad-patrascu).

   Documentation Copyrights:

   Copyright © 2022 www.opensips-solutions.com
