Kamailio-开源SIP软交换平台

中国第一个专注Kamailio SIP 软交换技术分享平台

用户工具

站点工具


ims_auth_ims_authentication_module_released

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

ims_auth_ims_authentication_module_released [2017/09/11 11:32] (当前版本)
james_zhu 创建
行 1: 行 1:
 +====== ims_auth Module ======
  
 +==== Dragos Vingarzan ​ ====
 +
 +FhG Fokus\\ ​
 +
 +''<​[[Dragos.Vingarzan@fokus.fraunhofer.de|Dragos.Vingarzan@fokus.fraunhofer.de]]>''​
 +
 +==== Jason Penton ====
 +
 +Smile Communications\\ ​
 +
 +''<​[[jason.penton@smilecoms.com|jason.penton@smilecoms.com]]>''​
 +
 +==== Richard Good ====
 +
 +Smile Communications\\ ​
 +
 +''<​[[richard.good@smilecoms.com|richard.good@smilecoms.com]]>''​
 +
 +=== Edited by ===
 +
 +==== Carsten Bock ====
 +
 +ng-voice GmbH\\ ​
 +
 +Copyright © 2007 FhG FOKUS
 +
 +Copyright © 2012 Smile Communications
 +
 +Copyright © 2015 ng-voice GmbH
 +
 +----
 +
 +**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)** ​
 +      * **3.11. cxdx_dest_host (string)** ​
 +      * **3.12. max_nonce_reuse (integer)** ​
 +      * **3.13. add_authinfo_hdr (integer)** ​
 +      * **3.14. ignore_failed_auth (integer)** ​
 +      * **3.15. av_check_only_impu (integer)** ​
 +    * **4. Functions** ​
 +      * **4.1. ims_www_authorize(realm,​ table)** ​
 +      * **4.2. ims_www_authenticate(realm)** ​
 +      * **4.3. ims_www_challenge(route_block,​ realm)** ​
 +      * **4.4. ims_www_challenge(route_block,​ realm, algorithm)** ​
 +      * **4.5. ims_proxy_challenge(route_block,​ realm, table)** ​
 +      * **4.6. 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. registration_qop parameter usage** ​
 +  * **1.9. cxdx_forced_peer parameter usage** ​
 +  * **1.10. cxdx_dest_realm parameter usage** ​
 +  * **1.11. cxdx_dest_host parameter usage** ​
 +  * **1.12. max_nonce_reuse parameter usage** ​
 +  * **1.13. add_authinfo_hdr parameter usage** ​
 +  * **1.14. ignore_failed_auth parameter usage** ​
 +  * **1.15. av_check_only_impu parameter usage** ​
 +  * **1.16. www_authorize usage** ​
 +  * **1.17. ims_www_challenge usage** ​
 +  * **1.18. ims_www_challenge usage** ​
 +  * **1.19. 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)** ​
 +    * **3.11. cxdx_dest_host (string)** ​
 +    * **3.12. max_nonce_reuse (integer)** ​
 +    * **3.13. add_authinfo_hdr (integer)** ​
 +    * **3.14. ignore_failed_auth (integer)** ​
 +    * **3.15. av_check_only_impu (integer)** ​
 +  * **4. Functions** ​
 +    * **4.1. ims_www_authorize(realm,​ table)** ​
 +    * **4.2. ims_www_authenticate(realm)** ​
 +    * **4.3. ims_www_challenge(route_block,​ realm)** ​
 +    * **4.4. ims_www_challenge(route_block,​ realm, algorithm)** ​
 +    * **4.5. ims_proxy_challenge(route_block,​ realm, table)** ​
 +    * **4.6. 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 ====
 +
 +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) ====
 +
 +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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​name",​ "​sip:​scscf3.ims.smilecoms.com:​6060"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​auth_data_hash_size",​ 1024)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​auth_vector_timeout",​ "​domain"​)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​auth_data_timeout",​ 60)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​av_request_at_once",​ 1)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​av_request_at_sync",​ 1)
 +...
 +</​code>​
 +
 +\\ ==== 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**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​registration_default_algorithm",​ "​HSS-Selected"​)
 +...
 +</​code>​
 +
 +\\ ==== 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. ''​registration_qop''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​registration_qop",​ "​auth-int"​)
 +...
 +</​code>​
 +
 +\\ ==== 3.9. cxdx_forced_peer (string) ====
 +
 +FQDN of Diameter Peer (HSS) to use for communication (MAR). If you use this, the routing defined in your diameter xml configuration file (CDP) will be ignored and as a result you will lose the benefits of load balancing and failover.
 +
 +Default value is “”.
 +
 +**Example 1.9. ''​cxdx_forced_peer''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​cxdx_forced_peer",​ "​hss.ims.smilecoms.com"​)
 +...
 +</​code>​
 +
 +\\ ==== 3.10. cxdx_dest_realm (string) ====
 +
 +Destination realm to be used in Diameter messages to HSS
 +
 +Default value is “ims.smilecoms.com”.
 +
 +**Example 1.10. ''​cxdx_dest_realm''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​cxdx_dest_realm",​ "​ims.smilecoms.com"​)
 +...
 +</​code>​
 +
 +\\ ==== 3.11. cxdx_dest_host (string) ====
 +
 +Destination Host to be used in Diameter-MAR messages to HSS
 +
 +Default value is “” (not set).
 +
 +**Example 1.11. ''​cxdx_dest_host''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​cxdx_dest_host",​ "​hss.ims.ng-voice.com"​)
 +...
 +</​code>​
 +
 +\\ ==== 3.12. max_nonce_reuse (integer) ====
 +
 +Defines, how many times a nonce can be reused (provided nc is incremented)
 +
 +Default value is “0” (don't allow reuse).
 +
 +**Example 1.12. ''​max_nonce_reuse''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​max_nonce_reuse",​ 1)
 +...
 +</​code>​
 +
 +\\ ==== 3.13. add_authinfo_hdr (integer) ====
 +
 +Should an Authentication-Info header be added on 200 OK responses?
 +
 +Default value is “1” (add Authentication-Info header).
 +
 +**Example 1.13. ''​add_authinfo_hdr''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​add_authinfo_hdr",​ 0)
 +...
 +</​code>​
 +
 +\\ ==== 3.14. ignore_failed_auth (integer) ====
 +
 +Ignore invalid passwords (only IMPI/IMPU is checked).
 +
 +It should be used only for testing, e.g. load balancing with SIPP where we don't want to worry about auth.
 +
 +Default value is “0” (don't ingnore the failed authentication).
 +
 +**Example 1.14. ''​ignore_failed_auth''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​ignore_failed_auth",​ 1)
 +...
 +</​code>​
 +
 +\\ ==== 3.15. av_check_only_impu (integer) ====
 +
 +When storing the authentication vectors for an account, use either IMPI/IMPU (=0, default) or IMPU (=1).
 +
 +In case the IMPI is different from the IMPU, this option needs to be enabled to allow registration from classic "​SIP-clients",​ such as Snom phones and others, as they do not send an authentication username in the first REGISTER.
 +
 +Default value is “0” (store authentication vectors based on IMPI/IMPU).
 +
 +**Example 1.15. ''​av_check_only_impu''​ parameter usage**
 +
 +<​code>​
 +...
 +modparam("​ims_auth",​ "​av_check_only_impu",​ 1)
 +...
 +</​code>​
 +
 +\\ ===== 4. Functions =====
 +
 +==== 4.1. ims_www_authorize(realm,​ table) ====
 +
 +The function verifies credentials according to [[http://​www.ietf.org/​rfc/​rfc2617.txt|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.16. ''​www_authorize''​ usage**
 +
 +<​code>​
 +...
 +if (!www_authorize("​kamailio.org",​ "​subscriber"​)) {
 +        www_challenge(""​REG_MAR_REPLY"",​ "​kamailio.org",​ "​1"​);​
 +};         
 +...
 +</​code>​
 +
 +\\ ==== 4.2. ims_www_authenticate(realm) ====
 +
 +It is the 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(route_block,​ realm) ====
 +
 +Name alias: proxy_authorize(realm,​ table)
 +
 +The function verifies credentials according to [[http://​www.ietf.org/​rfc/​rfc2617.txt|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:
 +
 +  * Route block to resume after async MAR Diameter reply. ​
 +  * 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. ​
 +
 +This function can be used from REQUEST_ROUTE.
 +
 +**Example 1.17. ims_www_challenge usage**
 +
 +<​code>​
 +...
 +if (!proxy_authorize("​$fd",​ "​subscriber)) {
 +        proxy_challenge(""​REG_MAR_REPLY","​$fd"​); ​ # Realm will be autogenerated
 +};
 +...
 +            ...
 +route[REG_MAR_REPLY]
 +{
 +     #this is async so to know status we have to check the reply avp
 +     ​xlog("​L_DBG","​maa_return code is $avp(s:​maa_return_code)\n"​); ​  
 +
 +     ​switch ($avp(s:​maa_return_code)){
 +             case 1: #success
 +                     ​xlog("​L_DBG",​ "MAR success - 401/407 response sent from module\n"​);​
 +                     ​break;​
 +             case -1: #failure
 +                     ​xlog("​L_ERR",​ "MAR failure - error response sent from module\n"​);​
 +                     ​break;​
 +             case -2: #error
 +                     ​xlog("​L_ERR",​ "MAR error - sending error response now\n"​);​
 +                     ​t_reply("​500",​ "MAR failed"​);​
 +                     ​break;​
 +             ​default:​
 +                     ​xlog("​L_ERR",​ "​Unknown return code from MAR, value is [$avp(s:​uaa_return_code)]\n"​);​
 +                     ​t_reply("​500",​ "​Unknown response code from MAR");
 +                     ​break;​
 +     }
 +     ​exit; ​          
 +}
 +</​code>​
 +
 +\\ ==== 4.4. ims_www_challenge(route_block,​ realm, algorithm) ====
 +
 +Same as 4.3 except here there is the addiional option to specify the authorisation algorithm
 +
 +  * algorithm - The algorithm to be used when challenging the client. Can be AKAv1-MD5, AKAv2-MD5, MD5, or HSS-Selected. If left as an empty string, the default algorithm will be chosen according to the parameter registration_default_algorithm (see section 3.7) 
 +
 +This function can be used from REQUEST_ROUTE.
 +
 +**Example 1.18. ims_www_challenge usage**
 +
 +<​code>​
 +...
 + if (!ims_www_authenticate(NETWORKNAME)) {
 +                #user has not been authenticated. Lets send a challenge via 401 Unauthorized
 +                if ($? == -2) {
 +                        t_reply("​403",​ "​Authentication Failed"​);​
 +                        exit;
 +                } else if ($? == -3) {
 +                        t_reply("​400",​ "Bad Request"​);​
 +                        exit;
 +                } else if ($? == -9) {
 +                        xlog("​L_DBG",​ "​Authentication re-sync requested\n"​);​
 +                        ims_www_resync_auth("​REG_RESYNC_REPLY",​ "​$td"​);​
 +                        exit;
 +                } else {
 +                        xlog("​L_DBG","​About to challenge! auth_ims\n"​); ​
 +                        ims_www_challenge("​REG_MAR_REPLY",​ "​$td",​ "​MD5"​);​
 +                        exit;
 +                }
 +        }
 +</​code>​
 +
 +\\ ==== 4.5. ims_proxy_challenge(route_block,​ realm, table) ====
 +
 +Name alias: proxy_authorize(realm,​ table)
 +
 +The function verifies credentials according to [[http://​www.ietf.org/​rfc/​rfc2617.txt|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:
 +
 +  * Route block to resume after async MAR Diameter reply. ​
 +  * 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.19. proxy_authorize usage**
 +
 +<​code>​
 +...
 +if (!proxy_authorize("​$fd",​ "​subscriber)) {
 +        proxy_challenge("​REG_MAR_REPLY","​$fd",​ "​1"​); ​ # Realm will be autogenerated
 +};
 +...
 +route[REG_MAR_REPLY]
 +{
 +     #this is async so to know status we have to check the reply avp
 +     ​xlog("​L_DBG","​maa_return code is $avp(s:​maa_return_code)\n"​); ​  
 +
 +     ​switch ($avp(s:​maa_return_code)){
 +             case 1: #success
 +                     ​xlog("​L_DBG",​ "MAR success - 401/407 response sent from module\n"​);​
 +                     ​break;​
 +             case -1: #failure
 +                     ​xlog("​L_ERR",​ "MAR failure - error response sent from module\n"​);​
 +                     ​break;​
 +             case -2: #error
 +                     ​xlog("​L_ERR",​ "MAR error - sending error response now\n"​);​
 +                     ​t_reply("​500",​ "MAR failed"​);​
 +                     ​break;​
 +             ​default:​
 +                     ​xlog("​L_ERR",​ "​Unknown return code from MAR, value is [$avp(s:​uaa_return_code)]\n"​);​
 +                     ​t_reply("​500",​ "​Unknown response code from MAR");
 +                     ​break;​
 +     }
 +     ​exit; ​          
 +}            ​
 +...
 +</​code>​
 +
 +\\ ==== 4.6. 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) ====
 +
 +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.
ims_auth_ims_authentication_module_released.txt · 最后更改: 2017/09/11 11:32 由 james_zhu