Identity 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. privKey (string)
              1.3.2. authCert (string)
              1.3.3. certUri (string)
              1.3.4. verCert (string)
              1.3.5. caList (string)
              1.3.6. crlList (string)
              1.3.7. useCrls (integer)

        1.4. Exported Functions

              1.4.1. authservice()
              1.4.2. verifier()

        1.5. Known Limitations

   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 privKey parameter
   1.2. Set authCert parameter
   1.3. Set certUri parameter
   1.4. Set verCert parameter
   1.5. Set caList parameter
   1.6. Set crlList parameter
   1.7. Set privKey parameter
   1.8. authservice() usage
   1.9. verifier() usage

Chapter 1. Admin Guide

1.1. Overview

   This module adds support for SIP Identity (see RFC 4474).

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * No dependencies on other OpenSIPS modules.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * openssl (libssl).

1.3. Exported Parameters

1.3.1. privKey (string)

   Filename of private RSA-key of authentication service. This
   file must be in PEM format.

   Example 1.1. Set privKey parameter
...
modparam("identity", "privKey", "/etc/openser/privkey.pem")
...

1.3.2. authCert (string)

   Filename of certificate which belongs to privKey. This file
   must be in PEM format.

   Example 1.2. Set authCert parameter
...
modparam("identity", "authCert", "/etc/openser/cert.pem")
...

1.3.3. certUri (string)

   URI from which the certificate of the authentication service
   can be acquired. This string will be placed in the
   Identity-Info header.

   Example 1.3. Set certUri parameter
...
modparam("identity", "certUri", "http://www.myserver.com/cert.pem")
...

1.3.4. verCert (string)

   Path containing certificates for the verifier. Certificates
   must be in PEM format. The URI in the Identity-Info header
   field is used to find the corresponding certificate for the
   request. For this purpose the verifier replaces every character
   which is not alphanumeric, no “_” and no “.” with a “-”. A “.”
   at the beginning of the URI is forbidden. If the URI is
   “http://www.test.com/cert.pem” the verifier will look for the
   file “http---www.test.com-cert.pem”, for example. It is also
   possible to store a whole certificate chain in a file. In this
   case certificates must be in right order, end certificate
   first.

   Example 1.4. Set verCert parameter
...
modparam("identity", "verCert", "/etc/openser/verCert/")
...

1.3.5. caList (string)

   File containing all trusted (root) certificates for the
   verifier. Certificates must be in PEM format.

   Example 1.5. Set caList parameter
...
modparam("identity", "caList", "/etc/openser/caList.pem")
...

1.3.6. crlList (string)

   File containing certificate revocation lists (crls) for the
   verifier. Setting this parameter is only necessary if useCrls
   is set to “1”.

   Example 1.6. Set crlList parameter
...
modparam("identity", "crlList", "/etc/openser/crls.pem")
...

1.3.7. useCrls (integer)

   Switch to decide whether to use revocation lists (“1”) or not
   (“0”).

   Default value is “0”.

   Example 1.7. Set privKey parameter
...
modparam("identity", "useCrls", 1)
...

1.4. Exported Functions

1.4.1.  authservice()

   This function performs the steps of an authentication service.
   Before you call this function, you have to ensure that
     * the server is responsible for this request (from URI
       matches local SIP domain)
     * the sender of the request is authorized to claim the
       identity given in the From header field.

   This function returns the following values:
     * -3: Date header field does not match validity period of
       cert. Identity header has not been added.
     * -2: message out of time (e.g. message to old), Identity
       header has not been added.
     * -1: An error occurred.
     * 1: everything OK, Identity header has been added.

   This function can be used from REQUEST_ROUTE.

   Example 1.8. authservice() usage
...
# CANCEL and ACK cannot be challenged
if (($rm=="CANCEL") || ($rm"ACK"))
{
    route(1); # forward
    exit;
}

# some clients (e.g. Kphone) do not answer, when a BYE is challenged
if ($rm=="BYE")
{
    route(1); # forward
    exit;
}

### Authentication Service ###

# check whether I am authoritative
if($fd!="mysipdomain.de")
{
    route(1); # forward
    exit;
}

if(!proxy_authorize("mysipdomain.de","subscriber"))
{
    proxy_challenge("mysipdomain.de",0);
    exit;
}

if ($au!=$fU)
{
    sl_send_reply(403, "Use From=ID");
    exit;
}
consume_credentials();

authservice();
switch($retcode)
{
    case -3:
        xlog("L_DBG" ,"authservice: Date header field does not match val
idity period of cert\n");
        break;
    case -2:
        xlog("L_DBG" ,"authservice: msg out of time (max. +- 10 minutes
allowed)\n");
        break;
    case -1:
        xlog("L_DBG" ,"authservice: ERROR, returnvalue: -1\n");
        break;
    case 1:
        xlog("L_DBG" ,"authservice: everything OK\n");
        break;
    default:
        xlog("L_DBG" ,"unknown returnvalue of authservice\n");

}

route(1); #forward with ($retcode=1) or without ($retcode!=1) Identity h
eader
...

1.4.2.  verifier()

   This function performs the steps of an verifier. The returned
   code tells you the result of the verification:
     * -438: Signature does not correspond to the message.
       438-response should be send.
     * -437: Certificate cannot be validated. 437-response should
       be send.
     * -436: Certificate is not available. 436-response should be
       send.
     * -428: Message does not have an Identity header.
       428-response should be send.
     * -3: Error verifying Date header field.
     * -2: Authentication service is not authoritative.
     * -1: An unknown error occurred.
     * 1: verification OK

   This function can be used from REQUEST_ROUTE.

   Example 1.9. verifier() usage
...
# we have to define the same exceptions as we did for the authentication
 service
if (($rm=="CANCEL") || ($rm"ACK"))
{
    route(1); # forward
    exit;
}

if ($rm=="BYE")
{
    route(1); # forward
    exit;
}

verifier();
switch($retcode)
{
    case -438:
        xlog("L_DBG" ,"verifier: returnvalue: -438\n");
        sl_send_reply(438, "Invalid Identity Header");
        exit;
        break;
    case -437:
        xlog("L_DBG" ,"verifier: returnvalue: -437\n");
        sl_send_reply(437, "Unsupported Certificate");
        exit;
        break;
    case -436:
        xlog("L_DBG" ,"verifier: returnvalue: -436\n");
        sl_send_reply(436, "Bad Identity-Info");
        exit;
        break;
    case -428:
        xlog("L_DBG" ,"verifier: returnvalue: -428\n");
        sl_send_reply(428, "Use Identity Header");
        exit;
        break;
    case -3:
        xlog("L_DBG" ,"verifier: error verifying Date header field\n");
        exit;
        break;
    case -2:
        xlog("L_DBG" ,"verifier: authentication service is not authorita
tive\n");
        exit;
        break;
    case -1:
        xlog("L_DBG" ,"verifier: ERROR, returnvalue: -1\n");
        exit;
        break;
    case 1:
        xlog("L_DBG" ,"verifier: verification OK\n");
        route(1); # forward
        exit;
        break;
    default:
        xlog("L_DBG" ,"unknown returnvalue of verifier\n");
        exit;
}
exit;
...

1.5. Known Limitations

     * Certificates are not downloaded. They have to be stored
       locally.
     * Call-IDs of valid requests containing an Identity header
       are not recorded. Hence the verifier does not provide full
       replay protection.
     * Authentication service and verifier use the original
       request. Changes resulting from message processing in
       OpenSER script are ignored.

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. Alexander Christ 23 1 2571 0
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 14 12 28 19
   3. Liviu Chircu (@liviuchircu) 12 9 23 69
   4. Razvan Crainea (@razvancrainea) 11 9 82 24
   5. Vlad Patrascu (@rvlad-patrascu) 6 4 15 16
   6. Sergio Gutierrez 4 2 7 2
   7. Maksym Sobolyev (@sobomax) 4 2 3 20
   8. Alexandra Titoc 3 2 7 0
   9. Ovidiu Sas (@ovidiusas) 3 1 18 2
   10. Julián Moreno Patiño 3 1 2 2

   All remaining contributors: Peter Lemenkov (@lemenkov), Saúl
   Ibarra Corretgé (@saghul).

   (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.  Alexandra Titoc                     Sep 2024 - Sep 2024
   2.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   3.  Maksym Sobolyev (@sobomax)          Sep 2020 - Feb 2023
   4.  Razvan Crainea (@razvancrainea)     Aug 2015 - Jan 2021
   5.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   6.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2009 - Apr 2019
   7.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   8.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   9.  Saúl Ibarra Corretgé (@saghul)      Oct 2014 - Oct 2014
   10. Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013

   All remaining contributors: Sergio Gutierrez, Alexander Christ.

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei
   Iancu (@bogdan-iancu), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Alexander Christ.

   Documentation Copyrights:

   Copyright © 2007 Alexander Christ, Cologne University of
   Applied Sciences