Table of Contents
List of Tables
List of Examples
The following modules must be loaded before this module:
No dependencies on other OpenSIPS modules.
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")
...
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")
...
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")
...
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.
File containing all trusted (root) certificates for the verifier. Certificates must be in PEM format.
File containing certificate revocation lists (crls) for the verifier. Setting this parameter is only necessary if useCrls is set to “1”.
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.
-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.
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 validity 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 header
...
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
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 authoritative\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;
...
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.
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
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
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