Auth Module

Jan Janak

FhG Fokus

Juha Heinanen

Song Networks

Bogdan-Andrei Iancu

Edited by

Jan Janak


Table of Contents
1. User's Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSER Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. secret (string)
1.3.2. nonce_expire (integer)
1.3.3. rpid_prefix (string)
1.3.4. rpid_suffix (string)
1.3.5. realm_prefix (string)
1.3.6. rpid_avp (string)
1.4. Exported Functions
1.4.1. www_challenge(realm, qop)
1.4.2. proxy_challenge(realm, qop)
1.4.3. consume_credentials()
1.4.4. is_rpid_user_e164()
1.4.5. append_rpid_hf()
1.4.6. append_rpid_hf(prefix, suffix)
2. Developer's Guide
3. Frequently Asked Questions
List of Examples
1-1. secret parameter example
1-2. nonce_expire parameter example
1-3. rpid_prefix parameter example
1-4. rpid_suffix parameter example
1-5. realm_prefix parameter example
1-6. rpid_avp parameter example
1-7. www_challenge usage
1-8. proxy_challenge usage
1-9. consume_credentials example
1-10. is_rpid_user_e164 usage
1-11. append_rpid_hf usage
1-12. append_rpid_hf(prefix, suffix) usage

Chapter 1. User's Guide

1.1. Overview

This is a generic module that itself doesn't provide all functions necessary for authentication but provides functions that are needed by all other authentication related modules (so called authentication backends).

We decided to break the authentication code into several modules because there are now more than one backends (currently database authentication and radius are supported). This allows us to create separate packages so uses can install and load only required functionality. This also allows us to avoid unnecessary dependencies in the binary packages.


1.2. Dependencies

1.2.1. OpenSER Modules

The module depends on the following modules (in the other words the listed modules must be loaded before this module):

  • sl -- Stateless replies


1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSER with this module loaded:

  • none


1.3. Exported Parameters

1.3.1. secret (string)

Secret phrase.

Default value is randomly generated string.

Example 1-1. secret parameter example

modparam("auth", "secret", "johndoessecretphrase")

1.3.2. 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 300 seconds.

Example 1-2. nonce_expire parameter example

modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s

1.3.3. rpid_prefix (string)

Prefix to be added to Remote-Party-ID header field just before the URI returned from either radius or database.

Default value is "".

Example 1-3. rpid_prefix parameter example

modparam("auth", "rpid_prefix", "Whatever <")

1.3.4. rpid_suffix (string)

Suffix to be added to Remote-Party-ID header field after the URI returned from either radius or database.

Default value is ";party=calling;id-type=subscriber;screen=yes".

Example 1-4. rpid_suffix parameter example

modparam("auth", "rpid_suffix", "@1.2.3.4>")

1.3.5. realm_prefix (string)

Prefix to be automatically strip from realm. As an alternative to SRV records (not all SIP clients support SRV lookup), a subdomain of the master domain can be defined for SIP purposes (like sip.mydomain.net pointing to same IP address as the SRV record for mydomain.net). By ignoring the realm_prefix "sip.", at authentication, sip.mydomain.net will be equivalent to mydomain.net .

Default value is empty string.

Example 1-5. realm_prefix parameter example

modparam("auth", "realm_prefix", "sip.")

1.3.6. rpid_avp (string)

Full AVP specification (ID, Name, Alias) for the AVP which stores the RPID value. It used to transport the RPID value from authntication backend modules (auth_db or auth_radius) or from script to the auth function append_rpid_hf and is_rpid_user_e164.

If defined to NULL string, all RPID functions will fail at runtime.

Default value is "rpid" (Name AVP - e.g, 'i:number', 's:string' or 'avp_alias_string').

Example 1-6. rpid_avp parameter example

modparam("auth", "rpid_avp", "i:13")
		

1.4. Exported Functions

1.4.1. www_challenge(realm, qop)

The function challenges a user agent. It will generate a WWW-Authorize header field containing a digest challenge, it will put the header field into a response generated from the request the server is processing and send the reply. Upon reception of such a reply the user agent should compute credentials and retry the request. For more information regarding digest authentication see RFC2617.

Meaning of the parameters is as follows:

  • realm - Realm is a opaque string that the user agent should present to the user so he can decide what username and password to use. Usually this is domain of the host the server is running on.

    If an empty string "" is used then the server will generate it from the request. In case of REGISTER requests To header field domain will be used (because this header field represents a user being registered), for all other messages From header field domain will be used.

    The string may contain pseudo variables.

  • qop - Value of this parameter can be either "1" or "0". When set to 1 then the server will put qop parameter in the challenge. When set to 0 then the server will not put qop parameter in the challenge. It is strongly recommended to use qop parameter, however there are still some user agents that cannot handle qop parameter properly so we made this optional. On the other hand there are still some user agents that cannot handle request without qop parameter too.

This function can be used from REQUEST_ROUTE.

Example 1-7. www_challenge usage

...
if (www_authorize("siphub.net", "subscriber")) {
	www_challenge("siphub.net", "1");
};
...

1.4.2. proxy_challenge(realm, qop)

The function challenges a user agent. It will generate a Proxy-Authorize header field containing a digest challenge, it will put the header field into a response generated from the request the server is processing and send the reply. Upon reception of such a reply the user agent should compute credentials and retry the request. For more information regarding digest authentication see RFC2617.

Meaning of the parameters is as follows:

  • realm - Realm is a opaque string that the user agent should present to the user so he can decide what username and password to use. Usually this is domain of the host the server is running on.

    If an empty string "" is used then the server will generate it from the request. From header field domain will be used as realm.

    The string may contain pseudo variables.

  • qop - Value of this parameter can be either "1" or "0". When set to 1 then the server will put qop parameter in the challenge. When set to 0 then the server will not put qop parameter in the challenge. It is strongly recommended to use qop parameter, however there are still some user agents that cannot handle qop parameter properly so we made this optional. On the other hand there are still some user agents that cannot handle request without qop parameter too.

This function can be used from REQUEST_ROUTE.

Example 1-8. proxy_challenge usage

...
if (!proxy_authorize("", "subscriber)) {
	proxy_challenge("", "1");  # Realm will be autogenerated
};
...

1.4.3. consume_credentials()

This function removes previously authorized credentials from the message being processed by the server. That means that the downstream message will not contain credentials there were used by this server. This ensures that the proxy will not reveal information about credentials used to downstream elements and also the message will be a little bit shorter. The function must be called after www_authorize or proxy_authorize.

This function can be used from REQUEST_ROUTE.

Example 1-9. consume_credentials example

...
if (www_authorize("", "subscriber)) {
    consume_credentials();
};
...

1.4.4. is_rpid_user_e164()

The function checks if the SIP URI received from the database or radius server and will potentially be used in Remote-Party-ID header field contains an E164 number (+followed by up to 15 decimal digits) in its user part. Check fails, if no such SIP URI exists (i.e. radius server or database didn't provide this information).

This function can be used from REQUEST_ROUTE.

Example 1-10. is_rpid_user_e164 usage

...
if (is_rpid_user_e164()) {
    # do something here
};
...

1.4.5. append_rpid_hf()

Appends to the message a Remote-Party-ID header that contains header 'Remote-Party-ID: ' followed by the saved value of the SIP URI received from the database or radius server followed by the value of module parameter radius_rpid_suffix. The function does nothing if no saved SIP URI exists.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-11. append_rpid_hf usage

...
append_rpid_hf();  # Append Remote-Party-ID header field
...

1.4.6. append_rpid_hf(prefix, suffix)

This function is the same as Section 1.4.5. The only difference is that it accepts two parameters--prefix and suffix to be added to Remote-Party-ID header field. This function ignores rpid_prefix and rpid_suffix parameters, instead of that allows to set them in every call.

Meaning of the parameters is as follows:

  • prefix - Prefix of the Remote-Party-ID URI. The string will be added at the begining of body of the header field, just before the URI.

  • suffix - Suffix of the Remote-Party-ID header field. The string will be appended at the end of the header field. It can be used to set various URI parameters, for example.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

Example 1-12. append_rpid_hf(prefix, suffix) usage

...
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");  # Append Remote-Party-ID header field
...

Chapter 2. Developer's Guide

The module does not provide any API to use in other OpenSER modules.


Chapter 3. Frequently Asked Questions

3.1. Where can I find more about OpenSER?
3.2. Where can I post a question about this module?
3.3. How can I report a bug?

3.1. Where can I find more about OpenSER?

Take a look at http://openser.org/.

3.2. Where can I post a question about this module?

First at all check if your question was already answered on one of our mailing lists:

E-mails regarding any stable OpenSER release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .

3.3. How can I report a bug?

Please follow the guidelines provided at: http://sourceforge.net/tracker/?group_id=139143.