#
# $Id: README,v 1.8 2002/09/30 22:30:44 jiri Exp $
#

Module depends on: mysql - Used as interface to database
                   sl    - Used for stateless replies



Exported parameters:
-------------------


Name:    db_url
Type:    string
Default: "sql://serro:47serro11@localhost/ser"
Desc:    Database url string in form "sql://<user>:<pass>@host/database"


Name:    user_column
Type:    string
Default: "user_id"
Desc:    Name of column containing usernames in subscriber table


Name:    realm_column
Type:    string
Default: "realm"
Desc:    Name of column containing realm in subscriber table


Name:    password_column
Type:    string
Default: "ha1"
Desc:    Name of column containing (plaintext passwords)/(ha1 strings) if
         calculate_ha1 parameter is set to true/false.


Name:    password_column_2
Type:    string
Default: "ha1b"
Desc:    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.
         
Name:    secret
Type:    string
Default: Randomly generated
Desc:    Nonce secret phrase


Name:    group_table
Type:    string
Default: "grp"
Desc:    Name of table containing group definitions


Name:    group_user_column
Type:    string
Default: "user"
Desc:    Name of column containing usernames in group table


Name:    group_group_column
Type:    string
Default" "grp"
Desc:    Name of column containing groups in group table


Name:    calculate_ha1
Type:    integer
Default: false
Desc:    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.


Name:    nonce_expire
Type:    integer
Default: 300
Desc:    Every nonce is valid only for a limited amount of time. This
         parameter specifies nonce validity interval in seconds. 
         
Name:    retry_count
Type:    integer
Default: 5
Desc:    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......
         



Exported Functions:
------------------


Name:   www_authorize
Params: realm - realm string
        table - subscriber table name
Desc:   Checks credentials in Authorization header field
Example:	if (!www_authorize( "iptel.org", "subscriber" )) {
				www_challenge(  "iptel.org", "0"; break; }

Name:   proxy_authorize
Params: realm - realm string
        table - subscriber database table name
Desc:   Checks credentials in Proxy-Authorization header field


Name:   www_challenge
Params: realm - realm string
        qop   - qop string, "1" means use qop parameter
                            "0" means do not use qop parameter
Desc:   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 brokn qop implementation, particularly M$ Messenger 4.6).


Name:   proxy_challenge
Params: realm - realm string
        qop   - qop string, "1" means use qop parameter
                            "0" means do not use qop parameter
Desc:   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).



Name:   is_user
Params: username - username string
Desc:   Checks if the specified username and matches the username
        in credentials. 
	Call after *_authorize, otherwise an error will be issued.



Name:   is_in_group
Params: group - group name
Desc:   Checks if the user specified in credentials is member of
        given group
	Call after *_authorize, otherwise an error will be issued.



Name:   check_to
Params: -
Desc:   Checks if the username given in credentials and username in
        To header field are equal
	Call after *_authorize, otherwise an error will be issued.
Example: if (method=="REGISTER" & proxy_authorize("iptel.org", "subscriber" ) {
	     if (!check_to) { 
	         sl_send_reply("403", "cheating: user!=to");
		 break;
	     }
         }


Name:   check_from
Params: -
Desc:   Checks if the username given in credentials and username in
        From header field are equal
	Call after *_authorize, otherwise an error will be issued.


Name:   consume_credentials
Params: -
Desc:   Removes previously authorized credentials from the message.
        The function must be called after {www,proxy}_authorize.


Name:   is_user_in
Params: hf - Use username in this header field, the following values
             are recognized:
             "From"        - Extract username from From URI
             "To"          - Extract username from To URI
             "Request-URI" - Extract username from Request URI
             "credentials" - Use username digest parameter
        group - grooup name
Desc:   Checks, if the user is in specified table

Usage Note
----------
As long as hop-by-hop requests ACK and CANCEL cannot be challenged
(see SIP specification), they typically include none or invalid
credentials. Avoid verification of these credentials in ACK/CANCEL
messages.  It would result in dropping valid requests.

