Auth Module

Jan Janak

   FhG Fokus
   <jan@iptel.org>

Juha Heinanen

   Song Networks
   <jh@song.fi>

Bogdan-Andrei Iancu

   <bogdan@opensips.org>

Edited by

Jan Janak

   <jan@iptel.org>

   Copyright © 2002, 2003 FhG FOKUS

   Copyright © 2005 Voice Sistem SRL
   Revision History
   Revision $Revision$ $Date: 2012-02-22 19:29:43 +0200
                              (Wed, 22 Feb 2012) $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Nonce Security
        1.3. Dependencies

              1.3.1. OpenSIPS Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. secret (string)
              1.4.2. nonce_expire (integer)
              1.4.3. rpid_prefix (string)
              1.4.4. rpid_suffix (string)
              1.4.5. realm_prefix (string)
              1.4.6. rpid_avp (string)
              1.4.7. username_spec (string)
              1.4.8. password_spec (string)
              1.4.9. calculate_ha1 (integer)
              1.4.10. disable_nonce_check (int)

        1.5. Exported Functions

              1.5.1. www_challenge(realm, qop)
              1.5.2. proxy_challenge(realm, qop)
              1.5.3. consume_credentials()
              1.5.4. is_rpid_user_e164()
              1.5.5. append_rpid_hf()
              1.5.6. append_rpid_hf(prefix, suffix)
              1.5.7. pv_www_authorize(realm)
              1.5.8. pv_proxy_authorize(realm)

   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. username_spec parameter usage
   1.8. password_spec parameter usage
   1.9. calculate_ha1 parameter usage
   1.10. disable_nonce_check parameter usage
   1.11. www_challenge usage
   1.12. proxy_challenge usage
   1.13. consume_credentials example
   1.14. is_rpid_user_e164 usage
   1.15. append_rpid_hf usage
   1.16. append_rpid_hf(prefix, suffix) usage
   1.17. pv_www_authorize usage
   1.18. pv_proxy_authorize usage

Chapter 1. Admin Guide

1.1. Overview

   This is a module that provides common functions that are needed
   by other authentication related modules. Also, it can perform
   authentication taking username and password from
   pseudo-variables.

1.2. Nonce Security

   The authentication mechanism offers protection against sniffing
   intrusion. The module generates and verifies the nonces so that
   they can be used only once (in an auth response). This is done
   by having a lifetime value and an index associated with every
   nonce. Using only an expiration value is not good enough
   because,as this value has to be of few tens of seconds, it is
   possible for someone to sniff on the network, get the
   credentials and then reuse them in another packet with which to
   register a different contact or make calls using the others's
   account. The index ensures that this will never be possible
   since it is generated as unique through the lifetime of the
   nonce.

   The default limit for the requests that can be authenticated is
   100000 in 30 seconds. If you wish to adjust this you can
   decrease the lifetime of a nonce( how much time to wait for a
   reply to a challenge). However, be aware not to set it to a too
   smaller value.

   However this mechanism does not work for architectures using a
   cluster of servers that share the same dns name for load
   balancing. In this case you can disable the nonce reusability
   check by setting the module parameter 'disable_nonce_check'.

1.3. Dependencies

1.3.1. OpenSIPS Modules

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

1.3.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * none

1.4. Exported Parameters

1.4.1. secret (string)

   Secret phrase used to calculate the nonce value.

   The default is to use a random value generated from the random
   source in the core.

   If you use multiple servers in your installation, and would
   like to authenticate on the second server against the nonce
   generated at the first one its necessary to explicitly set the
   secret to the same value on all servers. However, the use of a
   shared (and fixed) secret as nonce is insecure, much better is
   to stay with the default. Any clients should send the reply to
   the server that issued the request.

   Example 1.1. secret parameter example
modparam("auth", "secret", "johndoessecretphrase")

1.4.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 30 seconds.

   Example 1.2. nonce_expire parameter example
modparam("auth", "nonce_expire", 15)   # Set nonce_expire to 15s

1.4.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.4.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.4.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.4.6. rpid_avp (string)

   Full AVP specification for the AVP which stores the RPID value.
   It used to transport the RPID value from authentication 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 “$avp(rpid)”.

   Example 1.6. rpid_avp parameter example
modparam("auth", "rpid_avp", "$avp(13)")

1.4.7. username_spec (string)

   This name of the pseudo-variable that will hold the username.

   Default value is “NULL”.

   Example 1.7. username_spec parameter usage
modparam("auth", "username_spec", "$var(username)")

1.4.8. password_spec (string)

   This name of the pseudo-variable that will hold the password.

   Default value is “NULL”.

   Example 1.8. password_spec parameter usage
modparam("auth", "password_spec", "$avp(password)")

1.4.9. calculate_ha1 (integer)

   This parameter tells the server whether it should expect
   plaintext passwords in the pseudo-variable or a pre-calculated
   HA1 string.

   If the parameter is set to 1 then the server will assume that
   the “password_spec” pseudo-variable contains plaintext
   passwords and it will calculate HA1 strings on the fly. If the
   parameter is set to 0 then the server assumes the
   pseudo-variable contains the HA1 strings directly and will not
   calculate them.

   Default value of this parameter is 0.

   Example 1.9. calculate_ha1 parameter usage
modparam("auth", "calculate_ha1", 1)

1.4.10. disable_nonce_check (int)

   By setting this parameter you disable the security mechanism
   that protects against intrusion sniffing and does not allow
   nonces to be reused. But, because of the current
   implementation, having this enabled breaks auth for an
   architecture where load is balanced by having more servers with
   the same dns name. This parameter has to be set in this case.

   Default value is “0” (enabled).

   Example 1.10. disable_nonce_check parameter usage
modparam("auth", "disable_nonce_check", 1)

1.5. Exported Functions

1.5.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 will 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 an opaque string that the user agent
       should present to the user so it 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 request's 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 a qop parameter in
       the challenge. When set to 0 then the server will not put
       the qop parameter in the challenge. It is recommended to
       use the qop parameter, however there are still some user
       agents that cannot handle qop properly so we made this
       optional. On the other hand there are still some user
       agents that cannot handle request without a qop parameter
       too.
       Enabling this parameter does not improve security at the
       moment, because the sequence number is not stored and
       therefore could not be checked. Actually there is no
       information kept by the module during the challenge and
       response requests.

   This function can be used from REQUEST_ROUTE.

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

1.5.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 will 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 an opaque string that the user agent
       should present to the user so it 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 a qop parameter in
       the challenge. When set to 0 then the server will not put
       the qop parameter in the challenge. It is recommended to
       use the qop parameter, however there are still some user
       agents that cannot handle qop properly so we made this
       optional. On the other hand there are still some user
       agents that cannot handle request without a qop parameter
       too.
       Enabling this parameter don't improve the security at the
       moment, because the sequence number is not stored and
       therefore could not be checked. Actually there is no
       information kept by the module during the challenge and
       response requests.

   This function can be used from REQUEST_ROUTE.

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

1.5.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.13. consume_credentials example
...
if (www_authorize("", "subscriber)) {
    consume_credentials();
};
...

1.5.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.14. is_rpid_user_e164 usage
...
if (is_rpid_user_e164()) {
    # do something here
};
...

1.5.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.15. append_rpid_hf usage
...
append_rpid_hf();  # Append Remote-Party-ID header field
...

1.5.6.  append_rpid_hf(prefix, suffix)

   This function is the same as Section 1.5.5, “
   append_rpid_hf()”. 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.16. append_rpid_hf(prefix, suffix) usage
...
# Append Remote-Party-ID header field
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");
...

1.5.7.  pv_www_authorize(realm)

   The function verifies credentials according to RFC2617. If the
   credentials are verified successfully then the function will
   succeed and mark the credentials as authorized (marked
   credentials can be later used by some other functions). If the
   function was unable to verify the credentials for some reason
   then it will fail and the script should call www_challenge
   which will challenge the user again.

   Negative codes may be interpreted as follows:
     * -5 (generic error) - some generic error occurred and no
       reply was sent out;
     * -4 (no credentials) - credentials were not found in
       request;
     * -3 (stale nonce) - stale nonce;
     * -2 (invalid password) - valid user, but wrong password;
     * -1 (invalid user) - authentication user does not exist.

   Meaning of the parameters is as follows:
     * realm - Realm is an 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.

   This function can be used from REQUEST_ROUTE.

   Example 1.17. pv_www_authorize usage
...
$var(username)="abc";
$avp(password)="xyz";
if (pv_www_authorize("opensips.org")) {
        www_challenge("opensips.org", "1");
};
...

1.5.8.  pv_proxy_authorize(realm)

   The function verifies credentials according to RFC2617. If the
   credentials are verified successfully then the function will
   succeed and mark the credentials as authorized (marked
   credentials can be later used by some other functions). If the
   function was unable to verify the credentials for some reason
   then it will fail and the script should call proxy_challenge
   which will challenge the user again. For more about the
   negative return codes, see the above function.

   Meaning of the parameters is as follows:
     * realm - Realm is an 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.

   This function can be used from REQUEST_ROUTE.

   Example 1.18. pv_proxy_authorize usage
...
$var(username)="abc";
$avp(password)="xyz";
if (!pv_proxy_authorize("")) {
        proxy_challenge("", "1");  # Realm will be autogenerated
};
...
