mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
403 lines
12 KiB
403 lines
12 KiB
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>
|
|
|
|
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.
|