专注于VoIP,Opensips,Kamailio等技术,QQ群：QQ群：293697898
This page was saved using WebZIP 7.0.3.1030 offline browser (Unregistered) on 10/03/15 23:42:10. Address: http://kamailio.org/docs/modules/stable/modules/ims_auth.html Title: ims_auth Module • Size: 53048 • Last Modified: Wed, 03 Jun 2015 20:25:53 GMT ims_auth Module
Dragos Vingarzan
FhG Fokus
<Dragos.Vingarzan@fokus.fraunhofer.de>
Jason Penton
Smile Communications
<jason.penton@smilecoms.com>
Richard Good
Smile Communications
<richard.good@smilecoms.com>
Edited by
Carsten Bock
ng-voice GmbH
翻译
李 浩
<1354608370@qq.com>
Copyright © 2007 FhG FOKUS
Copyright © 2012 Smile Communications
目录
1. 用户指南
1. 概述
2. 依赖表
2.1. Kamailio 模块
2.2. 外部库和应用程序
3. 参数表
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. max_nonce_reuse (integer)
3.12. add_authinfo_hdr (integer)
3.13. ignore_failed_auth (integer)
3.14. av_check_only_impu (integer)
4. 函数表
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. 统计
5.1. MAR Timeouts (mar_timeouts)
5.2. Average MAR Response Time (mar_avg_response_time)
示例
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. max_nonce_reuse parameter usage
1.12. add_authinfo_hdr parameter usage
1.13. ignore_failed_auth parameter usage
1.14. av_check_only_impu parameter usage
1.15. www_authorize usage
1.16. ims_www_challenge usage
1.17. ims_www_challenge usage
1.18. proxy_authorize usage
Chapter 1. 用户指南
目录
1. 概述
2. 依赖表
2.1. Kamailio 模块
2.2. 外部库和应用程序
3. 参数表
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. max_nonce_reuse (integer)
3.12. add_authinfo_hdr (integer)
3.13. ignore_failed_auth (integer)
3.14. av_check_only_impu (integer)
4. 函数表
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. 统计
5.1. MAR Timeouts (mar_timeouts)
5.2. Average MAR Response Time (mar_avg_response_time)
1.概述
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.
这个模块包含了所有的IMS环境的认证相关的功能。模块不依赖于Kamailio验证模块或其它验证模块。 ims_auth模块依赖于CDP(C Diameter peer)模块与HSS按3GPP进行通信。
2.依赖表
2.1. Kamailio 模块
The Following mouldes must be loaded before this module:
依赖模块必须要本模块前加载：
TM - Transaction Manager
CDP - C Diameter Peer
CDP_AVP - CDP AVP Applications
2.2. 外部库和应用程序
This modules requires the internal IMS library.
依赖的外部库或应用程序必须在加载本模块前被安装
3.参数表
3.1. name (string)
This is the name of the SCSCF as identified in communication with the HSS (Server-Name AVP of MAR).
这是确定与HSS通信的SCSCF的名称
默认值： 'sip:scscf.ims.smilecoms.com:6060'.
示例 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). 默认值： fine for most people. Use the parameter if you really need to change it.
用来返回存储用户认证数据的hash table 的大小。默认值对于大多数人是合适的，但是如果你需要去改变它。
默认值： “1024”.
示例 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 ...
这个是时间，在几秒以内，如果没有回应，sentauth 数据是有效的。
默认值： “60”.
示例 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.
时间，在几秒内，auth vector是有效的
默认值： “60”.
示例 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.
几个auth vectorsd 在MAR的请求中
默认值： 1
示例 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.
几个auth vectors 在同步的请求中
默认值： 1.
示例 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.
没有指定这个值的话，则使用默认的认证算法
选项如下:
AKAV1-MD5
AKAV2-MD5
MD5
HSS-Selected - HSS will decide on auth algorithm
默认值： “AKAv1-MD5”.
示例 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. QOP选项用于设置认证要求
默认值： “auth,auth-int”.
示例 1.8. registration_qop parameter usage
...
modparam("ims_auth", "registration_qop", "auth-int")
...
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.
HSS的FQDN用于MAR通信。如果你使用这个，定义在diameter xml 配置文件(CDP)中的路由将被忽略并且你将失去负截均衡和故碍转移的好处。
默认值： “”.
示例 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
目标域用于给HSS的diameter消息
默认值： “ims.smilecoms.com”.
示例 1.10. cxdx_dest_realm parameter usage
...
modparam("ims_auth", "cxdx_dest_realm", "ims.smilecoms.com")
...
3.11. max_nonce_reuse (integer)
Defines, how many times a nonce can be reused (provided nc is incremented)
如果定义，多少次可重复使用一个noonce
默认值： “0” (don't allow reuse).
示例 1.11. max_nonce_reuse parameter usage
...
modparam("ims_auth", "max_nonce_reuse", 1)
...
3.12. add_authinfo_hdr (integer)
Should an Authentication-Info header be added on 200 OK responses?
在200OK的返回中添加一个认证消息头
默认值： “1” (add Authentication-Info header).
示例 1.12. add_authinfo_hdr parameter usage
...
modparam("ims_auth", "add_authinfo_hdr", 0)
...
3.13. ignore_failed_auth (integer)
Ignore invalid passwords (only IMPI/IMPU is checked).
忽略无效的密码(仅用于IMPI/IMPU检查)
It should be used only for testing, e.g. load balancing with SIPP where we don't want to worry about auth.
仅用来做测试，比如，使用SIPP负载均衡，我们不想得到认证错误。
默认值： “0” (don't ingnore the failed authentication).
示例 1.13. ignore_failed_auth parameter usage
...
modparam("ims_auth", "ignore_failed_auth", 1)
...
3.14. av_check_only_impu (integer)
When storing the authentication vectors for an account, use either IMPI/IMPU (=0, default) or IMPU (=1).
一个帐户存储的认证数据，使用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.
也许IMPI和IMPU是不同的，这个选项使用允许传统的SIP_clients可使用，如Snom phones或其它的，因为他们不会在第一次认证时发送认证用户名。
默认值： “0” (store authentication vectors based on IMPI/IMPU).
示例 1.14. av_check_only_impu parameter usage
...
modparam("ims_auth", "av_check_only_impu", 1)
...
4.函数表
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.
这个函数按照RFC2617检查认证。如果 认证成功那么函数将标记为授权(标记将被用于其它函数)。如果函数因为某些原因不能通过认证，那么它将失败 且脚本重新调用 www_challenge。
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.
参数的含义如下:
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.
Realm是一个含糊的字符串，用户代理应该向用户提出，他使用用户名和密码，通常使用正在运行中的服务器的doamin
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).
它必须是一个非空字符串。注册请求的header中domain(伪变量$td)可被使用(因为这个header字段代表用户要注册)，header中的domain可以被 其它信息所用($fd).
The string may contain pseudo variables.
字符串可以包含伪变量
table - Table to be used to lookup usernames and passwords (usually subscribers table).
用于查询用户名、密码的表(通常subscribers表)
这个函数可被用于 REQUEST_ROUTE.
示例 1.15. www_authorize usage
...
if (!www_authorize("kamailio.org", "subscriber")) {
www_challenge(""REG_MAR_REPLY"", "kamailio.org", "1");
};
...
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.
它等同于函数www_authenticate(realm, table)。这个函数是为了保证向后兼容的，因为用户以前进行身份验证是通过它。
4.3. ims_www_challenge(route_block, realm)
Name alias: proxy_authorize(realm, table)
别名：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.
这个函数按照RFC2617进行验证。 哪果验证成功，那么函数将做一个成功标记(标记将被用于其它函数)。如果不能因为某种原因不能通 过验证，脚本会重新调用proxy_challenge.
Negative return codes have the same meaning as for www_authenticate().
它和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.
这个函数可被用于 REQUEST_ROUTE.
示例 1.16. ims_www_challenge usage
...
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;
}
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
除了指定addiional选项中的认证算法外，其它与4.3一致。
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)
这个函数可被用于 REQUEST_ROUTE.
示例 1.17. ims_www_challenge usage
...
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;
}
}
4.5. ims_proxy_challenge(route_block, realm, table)
别名: 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.
这个函数按照 RFC2617进行验证。如果它验证成功 ，那么函数将做一个成功标记(标记将被用于其它函数)。如果不能因为某种原因不能通 过验证，脚本会重新调用 proxy_challenge
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.
示例 1.18. proxy_authorize usage
...
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;
}
...
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.
它和proxy_authenticate(realm, table)功能等同，这个也是为了保持向后兼容。
5.统计
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.