modules/ims_auth: Updated documentation

Updated documentation and added README for ims_auth modules

modules/ims_auth/README

@@ -0,0 +1,402 @@
+ims_auth Module
+
+Dragos Vingarzan
+
+   FhG Fokus
+   <[email protected]>
+
+Jason Penton
+
+   Smile Communications
+   <[email protected]>
+
+Richard Good
+
+   Smile Communications
+   <[email protected]>
+
+   Copyright © 2007 FhG FOKUS
+
+   Copyright © 2012 Smile Communications
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. name (string)
+              3.2. auth_data_hash_size (integer)
+              3.3. auth_vector_timeout (integer)
+              3.4. auth_data_timeout (int)
+              3.5. av_request_at_once (integer)
+              3.6. av_request_at_sync (integer)
+              3.7. registration_default_algorithm (string)
+              3.8. registration_qop (string)
+              3.9. cxdx_forced_peer (string)
+              3.10. cxdx_dest_realm (string)
+
+        4. Functions
+
+              4.1. ims_www_authorize(realm, table)
+              4.2. ims_www_authenticate(realm, table)
+              4.3. ims_www_challenge(realm, table)
+              4.4. ims_proxy_challenge(realm, table)
+              4.5. ims_proxy_authenticate(realm, table)
+
+        5. Statistics
+
+              5.1. MAR Timeouts (mar_timeouts)
+              5.2. Average MAR Response Time (mar_avg_response_time)
+
+   List of Examples
+
+   1.1. name parameter usage
+   1.2. auth_data_hash_size parameter usage
+   1.3. auth_vector_timeout parameter usage
+   1.4. password_column parameter usage
+   1.5. av_request_at_once parameter usage
+   1.6. av_request_at_sync parameter usage
+   1.7. registration_default_algorithm parameter usage
+   1.8. load_credentials parameter usage
+   1.9. cxdx_forced_peer parameter usage
+   1.10. version_table parameter usage
+   1.11. www_authorize usage
+   1.12. proxy_authorize usage
+   1.13. proxy_authorize usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. name (string)
+        3.2. auth_data_hash_size (integer)
+        3.3. auth_vector_timeout (integer)
+        3.4. auth_data_timeout (int)
+        3.5. av_request_at_once (integer)
+        3.6. av_request_at_sync (integer)
+        3.7. registration_default_algorithm (string)
+        3.8. registration_qop (string)
+        3.9. cxdx_forced_peer (string)
+        3.10. cxdx_dest_realm (string)
+
+   4. Functions
+
+        4.1. ims_www_authorize(realm, table)
+        4.2. ims_www_authenticate(realm, table)
+        4.3. ims_www_challenge(realm, table)
+        4.4. ims_proxy_challenge(realm, table)
+        4.5. ims_proxy_authenticate(realm, table)
+
+   5. Statistics
+
+        5.1. MAR Timeouts (mar_timeouts)
+        5.2. Average MAR Response Time (mar_avg_response_time)
+
+1. Overview
+
+   This module contains all authentication related functions for an IMS
+   environment. The module does not depend on the base Kamailio auth
+   modules as other auth modules do. Instead ims_auth is dependent on the
+   CDP (C Diameter Peer) modules for communicating with HSS as specified
+   in 3GPP specs.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The Following mouldes must be loaded before this module:
+     * TM - Transaction Manager
+     * CDP - C Diameter Peer
+     * CDP_AVP - CDP AVP Applications
+
+2.2. External Libraries or Applications
+
+   This modules requires the internal IMS library.
+
+3. Parameters
+
+   3.1. name (string)
+   3.2. auth_data_hash_size (integer)
+   3.3. auth_vector_timeout (integer)
+   3.4. auth_data_timeout (int)
+   3.5. av_request_at_once (integer)
+   3.6. av_request_at_sync (integer)
+   3.7. registration_default_algorithm (string)
+   3.8. registration_qop (string)
+   3.9. cxdx_forced_peer (string)
+   3.10. cxdx_dest_realm (string)
+
+3.1. name (string)
+
+   This is the name of the SCSCF as identified in communication with the
+   HSS (Server-Name AVP of MAR).
+
+   Default value is 'sip:scscf.ims.smilecoms.com:6060'.
+
+   Example 1.1. name parameter usage
+...
+modparam("ims_auth", "name", "sip:scscf3.ims.smilecoms.com:6060")
+...
+
+3.2. auth_data_hash_size (integer)
+
+   This is the size of the hash table used to store auth vectors (AV).
+   Default value is fine for most people. Use the parameter if you really
+   need to change it.
+
+   Default value is “1024”.
+
+   Example 1.2. auth_data_hash_size parameter usage
+...
+modparam("ims_auth", "auth_data_hash_size", 1024)
+...
+
+3.3. auth_vector_timeout (integer)
+
+   This is the time, in seconds, that a SENTauth vector is valid for. If
+   there is no response ...
+
+   Default value is “60”.
+
+   Example 1.3. auth_vector_timeout parameter usage
+...
+modparam("ims_auth", "auth_vector_timeout", "domain")
+...
+
+3.4. auth_data_timeout (int)
+
+   Time, in seconds, an used auth vector is valid for.
+
+   Default value is “60”.
+
+   Example 1.4. password_column parameter usage
+...
+modparam("ims_auth", "auth_data_timeout", 60)
+...
+
+3.5. av_request_at_once (integer)
+
+   How many auth vectors to request in MAR.
+
+   Default value is 1
+
+   Example 1.5. av_request_at_once parameter usage
+...
+modparam("ims_auth", "av_request_at_once", 1)
+...
+
+3.6. av_request_at_sync (integer)
+
+   How many auth vectors to request at sync. Default value is 1.
+
+   Example 1.6. av_request_at_sync parameter usage
+...
+modparam("ims_auth", "av_request_at_sync", 1)
+...
+
+3.7. registration_default_algorithm (string)
+
+   The default authentication algorithm to use for registration if one is
+   not specified.
+
+   Options are:
+     * AKAV1-MD5
+     * AKAV2-MD5
+     * MD5
+     * HSS-Selected - HSS will decide on auth algorithm
+
+   Default value is “AKAv1-MD5”.
+
+   Example 1.7. registration_default_algorithm parameter usage
+...
+modparam("ims_auth", "registration_default_algorithm", "HSS-Selected")
+...
+
+3.8. registration_qop (string)
+
+   The QOP options to put in the authorisation challenges.
+
+   Default value of this parameter is “auth,auth-int”.
+
+   Example 1.8. load_credentials parameter usage
+...
+modparam("ims_auth", "load_credentials", "auth-int")
+...
+
+3.9. cxdx_forced_peer (string)
+
+   FQDN of Diameter Peer (HSS) to use for communication (MAR)
+
+   Default value is “”.
+
+   Example 1.9. cxdx_forced_peer parameter usage
+...
+modparam("ims_auth", "cxdx_forced_peer", "hss.ims.smilecoms.com")
+...
+
+3.10. cxdx_dest_realm (string)
+
+   Destination realm to be used in Diameter messags to HSS
+
+   Default value is “ims.smilecoms.com”.
+
+   Example 1.10. version_table parameter usage
+...
+modparam("ims_auth", "cxdx_dest_realm", "ims.smilecoms.com")
+...
+
+4. Functions
+
+   4.1. ims_www_authorize(realm, table)
+   4.2. ims_www_authenticate(realm, table)
+   4.3. ims_www_challenge(realm, table)
+   4.4. ims_proxy_challenge(realm, table)
+   4.5. ims_proxy_authenticate(realm, table)
+
+4.1. ims_www_authorize(realm, table)
+
+   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:
+     * -1 (generic error) - some generic error occurred and no reply was
+       sent out;
+     * -2 (invalid password) - valid user, but wrong password;
+     * -3 (invalid user) - authentication user does not exist.
+
+   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.
+       It must not be empty string “”. In case of REGISTER requests To
+       header field domain (e.g., variable $td) can be used (because this
+       header field represents the user being registered), for all other
+       messages From header field domain can be used (e.g., variable $fd).
+       The string may contain pseudo variables.
+     * table - Table to be used to lookup usernames and passwords (usually
+       subscribers table).
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.11. www_authorize usage
+...
+if (!www_authorize("kamailio.org", "subscriber")) {
+        www_challenge("kamailio.org", "1");
+};
+...
+
+4.2. ims_www_authenticate(realm, table)
+
+   It is same function as www_authenticate(realm, table). This name is
+   kept for backward compatibility, since it was named this way first time
+   by it actually does user authentication.
+
+4.3. ims_www_challenge(realm, table)
+
+   Name alias: proxy_authorize(realm, table)
+
+   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.
+
+   Negative return codes have the same meaning as for www_authenticate().
+
+   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.
+       It must not be empty string “”. Apart of a static strinh, typical
+       value is From header field domain (e.g., variable $fd).
+       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.
+     * table - Table to be used to lookup usernames and passwords (usually
+       subscribers table).
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.12. proxy_authorize usage
+...
+if (!proxy_authorize("$fd", "subscriber)) {
+        proxy_challenge("$fd", "1");  # Realm will be autogenerated
+};
+...
+
+4.4. ims_proxy_challenge(realm, table)
+
+   Name alias: proxy_authorize(realm, table)
+
+   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.
+
+   Negative return codes have the same meaning as for www_authenticate().
+
+   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.
+       It must not be empty string “”. Apart of a static strinh, typical
+       value is From header field domain (e.g., variable $fd).
+       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.
+     * table - Table to be used to lookup usernames and passwords (usually
+       subscribers table).
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.13. proxy_authorize usage
+...
+if (!proxy_authorize("$fd", "subscriber)) {
+        proxy_challenge("$fd", "1");  # Realm will be autogenerated
+};
+...
+
+4.5. ims_proxy_authenticate(realm, table)
+
+   It is same function as proxy_authenticate(realm, table). This name is
+   kept for backward compatibility, since it was named this way first time
+   but it actually does user authentication.
+
+5. Statistics
+
+   5.1. MAR Timeouts (mar_timeouts)
+   5.2. Average MAR Response Time (mar_avg_response_time)
+
+5.1. MAR Timeouts (mar_timeouts)
+
+   The number of timeouts on sending a MAR. i.e. no response to MAR.
+
+5.2. Average MAR Response Time (mar_avg_response_time)
+
+   The average response time in milliseconds for MAR-MAA transaction.

modules/ims_auth/doc/ims_auth_admin.xml

@@ -72,26 +72,6 @@ modparam("ims_auth", "name", "sip:scscf3.ims.smilecoms.com:6060")
       </example>
     </section>
 
-    <section>
-      <title><varname>name</varname> (string)</title>
-
-      <para>This is the name of the SCSCF as identified in communication with
-      the HSS (Server-Name AVP of MAR).</para>
-
-      <para><emphasis> Default value is 'sip:scscf.ims.smilecoms.com:6060'.
-      </emphasis></para>
-
-      <example>
-        <title><varname>name</varname> parameter usage</title>
-
-        <programlisting format="linespecific">
-...
-modparam("ims_auth", "name", "sip:scscf3.ims.smilecoms.com:6060")
-...
-</programlisting>
-      </example>
-    </section>
-
     <section>
       <title><varname>auth_data_hash_size</varname> (integer)</title>