SIP Express Router v0.8.8 - Developer's Guide
<<< Previous		Next >>>

Basic Modules

Digest Authentication

The module exports functions needed for digest authentication.

The module depends on:

mysql - Used as interface to database.
sl - Used for stateless replies.

Exported Parameters

db_url - Database url string in form "sql://<user>:<pass>@host/database".
Type: string
Default: "sql://serro:47serro11@localhost/ser"
user_column - Name of column containing usernames in subscriber table.
Type: string
Default: "user_id"
realm_column - Name of column containing realm in subscriber table.
Type: string
Default: "realm"
password_column - Name of column containing (plaintext passwords)/(ha1 strings) if calculate_ha1 parameter is set to true/false.
Type: string
Default: "ha1"
password_column_2 - The parameter can be used if and only if USER_DOMAIN_HACK macro is set in defs.h header file. The column of this name contains alternate ha1 strings calculated from username containing also domain, for example username="jan@iptel.org". This hack is neccessary for some broken user agents. The parameter has no meaning if "calculate_ha1" is set to true.
Type: string
Default: "ha1b"
secret - Nonce secret phrase.
Type: string
Default: Randomly generated string.
group_table - Name of table containing group definitions.
Type: string
Default: "grp"
group_user_column - Name of column containing usernames in group table.
Type: string
Default: "user"
group_group_column - Name of column containing groups in group table.
Type: string
Default: "grp"
calculate_ha1 - If set to true, auth module assumes that "password_column" contains plaintext passwords and ha1 string will be calculated at runtime. If set to false, "password_column" must contain precalculated ha1 strings.
Type: integer
Default: false
nonce_expire - Every nonce is valid only for a limited amount of time. This parameter specifies nonce validity interval in seconds.
Type: integer
Default: 300
retry_count - This parameter specifies how many times a user is allowed to retry authentication with incorrect credentials. After that the user will receive 403 Forbidden and must retry with different credentials. This should prevent DoS attacks from misconfigured user agents which try to authenticate with incorrect password again and again and again.
Type: integer
Default: 5

Exported Functions

int www_authorize(struct sip_msg* msg, char* realm, char* table);
The function checks credentials in Authorization header field.
realm - Realm string
table - Subscriber table name
Example 1. www_authorize
if (!www_authorize( "iptel.org", "subscriber" )) { www_challenge( "iptel.org", "0"); break; }
int proxy_authorize(struct sip_msg* msg, char* realm, char* table);
The function checks credentials in Proxy-Authorization header field.
realm - Realm string
table - Subscriber table name
Example 2. proxy_authorize
if (!proxy_authorize( "iptel.org", "subscriber" )) { proxy_challenge( "iptel.org", "0"); break; }
int www_challenge(struct sip_msg* msg, char* realm, char* qop);
Challenges a user agent using WWW-Authenticate header field. The second parameter specifies if qop parameter (according to rfc2617) should be used or not. (Turning off is useful primarly to make UAC happy, which have a broken qop implementation, particularly M$ Messenger 4.6).
realm - Realm string
qop - Qop string, "1" means use qop parameter "0" means do not use qop parameter.
int proxy_challenge(struct sip_msg* msg, char* realm, char* qop);
Challenges a user agent using Proxy-Authenticate header field. The second parameter specifies if qop parameter (according to rfc2617) should be used or not. (Turning off is useful primarly to make UAC happy, which have a broken qop implementation, particularly M$ Messenger 4.6).
realm - Realm string
qop - Qop string, "1" means use qop parameter "0" means do not use qop parameter.
int is_user(struct sip_msg* msg, char* username, char* s);
Checks if the specified username and matches the username in credentials. Call after *_authorize, otherwise an error will be issued.
username - Username string.
s - Not used.
int is_in_group(struct sip_msg* msg, char* group, char* s);
Checks if the user specified in credentials is member of given group Call after *_authorize, otherwise an error will be issued.
group - Group name.
s - Not used.
int check_to(struct sip_msg* msg, char* s1, char* s2);
Checks if the username given in credentials and username in To header field are equal Call after *_authorize, otherwise an error will be issued.
s1 - Not used.
s2 - Not used.
Example 3. check_to
if (method=="REGISTER" & proxy_authorize("iptel.org", "subscriber" ) { if (!check_to) { sl_send_reply("403", "cheating: user!=to"); break; } }
int check_from(struct sip_msg* msg, char* s1, char* s2);
Checks if the username given in credentials and username in From header field are equal. Call after *_authorize, otherwise an error will be issued.
s1 - Not used.
s2 - Not used.
int consume_credentials(struct sip_msg* msg, char* s1, char* s2);
Removes previously authorized credentials from the message. The function must be called after {www,proxy}_authorize.
s1 - Not used.
s2 - Not used.
int is_user_in(struct sip_msg* msg, char* hf, char* group);
Checks, if the user is in specified table.
hf - Use username in this header field, the following values are recognized:
group - Group name.