Auth Module

Jan Janak

   FhG Fokus
   <jan@iptel.org>

Juha Heinanen

   Song Networks
   <jh@song.fi>

   Copyright © 2002, 2003 FhG FOKUS
   Revision History
   Revision $Revision: 1.16 $ $Date: 2007/11/28 21:31:41 $
     __________________________________________________________________

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.

Dependencies

   The module depends on the following modules (in the other words the
   listed modules must be loaded before this module):
     * sl. The modules needs sl module to send stateless replies.

Parameters

   Revision History
   Revision $Revision: 1.16 $ $Date: 2007/11/28 21:31:41 $

auth_extra_checks (flags)

   If set to a non-zero value, extra authentication checks will be
   enabled. The default value is 0 (old behaviour, no extra checks).

   Without the extra checks the nonce will protect only against expired
   values. Some reply attacks are still possible in the expire "window". A
   possible workarround is to always force qop authentification and always
   check the uri from the authorization header, but this would not work if
   an upstream proxy rewrites the uri and it will also not work with a lot
   of UA implementations.

   In this case the nonce value will be used only to hold the expire time
   (see nonce_expire) and an MD5 over it and some secret (the MD5 is used
   to make sure that nobody tampers with the nonce expire time).

   When the extra checks are enabled, the nonce will include and extra MD5
   over the selected part/parts of the message (see below) and some other
   secret. This will be used to check if the selected part of the message
   is the same when an UA tries to reuse the nonce, thus protecting or
   severely limiting reply attacks.

   The possible flag values for auth_extra_checks are: 1 for checking if
   the message uri changed (uses the whole uri), 2 for checking the
   callid, 4 for the from tag and 8 for the source ip (see nonce.h). For
   example setting auth_extra_checks to 6 would check if the callid or the
   from tag changed from the message for which the original nonce was
   generated (this would allow nonce reuse only within the same dialog and
   for the expire time). Note that enabling the extra checks will limit
   nonce caching by UAs, requiring extra challenges and roundtrips, but
   will provide much better protection.

   When the secret parameter is set and the extra checks are enabled, the
   first half of the secret will be used for the expire time MD5 and the
   other half for the extra checks MD5, so make sure you have a long
   secret (32 chars or longer are recommended).

   Example 1. Setting the auth_extra_checks module parameter
modparam("auth", "auth_extra_checks", 14) # callid | fromtag | srcip

secret (string)

   Default value is randomly generated string.

   Example 2. Setting secret module parameter
modparam("auth", "secret", "johndoessecretphrase")

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 3. nonce_expire example
modparam("auth", "nonce_expire", 600)   # Set nonce_expire to 600s

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 "" (empty string).

   Example 4. rpid_prefix
modparam("auth", "rpid_prefix", "Whatever <")

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 5. rpid_suffix
modparam("auth", "rpid_suffix", "@1.2.3.4>")

Functions

   Revision History
   Revision $Revision: 1.16 $ $Date: 2007/11/28 21:31:41 $

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.
     * 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.

   Example 6. www_challenge usage
...
if (www_authorize("iptel.org", "subscriber")) {
    www_challenge("iptel.org", "1");
};
...

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.
     * 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.

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

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.

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

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).

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

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.

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

append_rpid_hf(prefix, suffix)

   This function is the same as the function described in the section
   called "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 for 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.

   Example 11. append_rpid_hf(prefix, suffix) usage
...
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");  # Append Re
mote-Party-ID header field
...
