auth(k): fix proxy/ www_challenge function, extends docs a bit (port r5874)

 - proxy_challenge / www_challenge was not sending any reply, in case
    the nonce could not be created (with nonce_reuse = 0, default since 1.4)
 - added a note to the docs about return-values from the auth-module
 - regenerate README file

modules_k/auth/README

@@ -29,44 +29,43 @@ Jan Janak
 
    Copyright © 2005 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-                              (Mi, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Nonce Security
-        1.3. Dependencies
-
-              1.3.1. Kamailio Modules
-              1.3.2. External Libraries or Applications
-
-        1.4. Exported Parameters
-
-              1.4.1. secret (string)
-              1.4.2. nonce_expire (integer)
-              1.4.3. rpid_prefix (string)
-              1.4.4. rpid_suffix (string)
-              1.4.5. realm_prefix (string)
-              1.4.6. rpid_avp (string)
-              1.4.7. username_spec (string)
-              1.4.8. password_spec (string)
-              1.4.9. calculate_ha1 (integer)
-              1.4.10. nonce_reuse (integer)
-
-        1.5. Exported Functions
-
-              1.5.1. www_challenge(realm, qop)
-              1.5.2. proxy_challenge(realm, qop)
-              1.5.3. consume_credentials()
-              1.5.4. is_rpid_user_e164()
-              1.5.5. append_rpid_hf()
-              1.5.6. append_rpid_hf(prefix, suffix)
-              1.5.7. pv_www_authorize(realm)
-              1.5.8. pv_proxy_authorize(realm)
+        1. Overview
+        2. Nonce Security
+        3. Dependencies
+
+              3.1. Kamailio Modules
+              3.2. External Libraries or Applications
+
+        4. Exported Parameters
+
+              4.1. secret (string)
+              4.2. nonce_expire (integer)
+              4.3. rpid_prefix (string)
+              4.4. rpid_suffix (string)
+              4.5. realm_prefix (string)
+              4.6. rpid_avp (string)
+              4.7. username_spec (string)
+              4.8. password_spec (string)
+              4.9. calculate_ha1 (integer)
+              4.10. nonce_reuse (integer)
+
+        5. Exported Functions
+
+              5.1. www_challenge(realm, qop)
+              5.2. proxy_challenge(realm, qop)
+              5.3. consume_credentials()
+              5.4. is_rpid_user_e164()
+              5.5. append_rpid_hf()
+              5.6. append_rpid_hf(prefix, suffix)
+              5.7. pv_www_authorize(realm)
+              5.8. pv_proxy_authorize(realm)
 
    List of Examples
 
@@ -91,78 +90,119 @@ Jan Janak
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   Table of Contents
+
+   1. Overview
+   2. Nonce Security
+   3. Dependencies
+
+        3.1. Kamailio Modules
+        3.2. External Libraries or Applications
+
+   4. Exported Parameters
+
+        4.1. secret (string)
+        4.2. nonce_expire (integer)
+        4.3. rpid_prefix (string)
+        4.4. rpid_suffix (string)
+        4.5. realm_prefix (string)
+        4.6. rpid_avp (string)
+        4.7. username_spec (string)
+        4.8. password_spec (string)
+        4.9. calculate_ha1 (integer)
+        4.10. nonce_reuse (integer)
+
+   5. Exported Functions
+
+        5.1. www_challenge(realm, qop)
+        5.2. proxy_challenge(realm, qop)
+        5.3. consume_credentials()
+        5.4. is_rpid_user_e164()
+        5.5. append_rpid_hf()
+        5.6. append_rpid_hf(prefix, suffix)
+        5.7. pv_www_authorize(realm)
+        5.8. pv_proxy_authorize(realm)
 
-   This is a module that provides common functions that are needed
-   by other authentication related modules. Also, it can perform
-   authentication taking username and password from
-   pseudo-variables.
+1. Overview
 
-1.2. Nonce Security
+   This is a module that provides common functions that are needed by
+   other authentication related modules. Also, it can perform
+   authentication taking username and password from pseudo-variables.
+
+2. Nonce Security
 
    The authentication mechanism offers protection against sniffing
-   intrusion. The module generates and verifies the nonces so that
-   they can be used only once (in an auth response). This is done
-   by having a lifetime value and an index associated with every
-   nonce. Using only an expiration value is not good enough
-   because,as this value has to be of few tens of seconds, it is
-   possible for someone to sniff on the network, get the
-   credentials and then reuse them in another packet with which to
-   register a different contact or make calls using the others's
-   account. The index ensures that this will never be possible
-   since it is generated as unique through the lifetime of the
-   nonce.
-
-   The default limit for the requests that can be authenticated is
-   100000 in 30 seconds. If you wish to adjust this you can
-   decrease the lifetime of a nonce( how much time to wait for a
-   reply to a challenge). However, be aware not to set it to a too
-   small value.
-
-1.3. Dependencies
-
-1.3.1. Kamailio Modules
-
-   The module depends on the following modules (in the other words
-   the listed modules must be loaded before this module):
+   intrusion. The module generates and verifies the nonces so that they
+   can be used only once (in an auth response). This is done by having a
+   lifetime value and an index associated with every nonce. Using only an
+   expiration value is not good enough because,as this value has to be of
+   few tens of seconds, it is possible for someone to sniff on the
+   network, get the credentials and then reuse them in another packet with
+   which to register a different contact or make calls using the others's
+   account. The index ensures that this will never be possible since it is
+   generated as unique through the lifetime of the nonce.
+
+   The default limit for the requests that can be authenticated is 100000
+   in 30 seconds. If you wish to adjust this you can decrease the lifetime
+   of a nonce( how much time to wait for a reply to a challenge). However,
+   be aware not to set it to a too small value.
+
+3. Dependencies
+
+   3.1. Kamailio Modules
+   3.2. External Libraries or Applications
+
+3.1. Kamailio Modules
+
+   The module depends on the following modules (in the other words the
+   listed modules must be loaded before this module):
      * sl -- Stateless replies
        pv -- Pseudo-variables
 
-1.3.2. External Libraries or Applications
+3.2. External Libraries or Applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module loaded:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * none
 
-1.4. Exported Parameters
+4. Exported Parameters
+
+   4.1. secret (string)
+   4.2. nonce_expire (integer)
+   4.3. rpid_prefix (string)
+   4.4. rpid_suffix (string)
+   4.5. realm_prefix (string)
+   4.6. rpid_avp (string)
+   4.7. username_spec (string)
+   4.8. password_spec (string)
+   4.9. calculate_ha1 (integer)
+   4.10. nonce_reuse (integer)
 
-1.4.1. secret (string)
+4.1. secret (string)
 
    Secret phrase used to calculate the nonce value.
 
-   The default is to use a random value generated from the random
-   source in the core.
+   The default is to use a random value generated from the random source
+   in the core.
 
-   If you use multiple servers in your installation, and would
-   like to authenticate on the second server against the nonce
-   generated at the first one its necessary to explicitly set the
-   secret to the same value on all servers. However, the use of a
-   shared (and fixed) secret as nonce is insecure, much better is
-   to stay with the default. Any clients should send the reply to
-   the server that issued the request.
+   If you use multiple servers in your installation, and would like to
+   authenticate on the second server against the nonce generated at the
+   first one its necessary to explicitly set the secret to the same value
+   on all servers. However, the use of a shared (and fixed) secret as
+   nonce is insecure, much better is to stay with the default. Any clients
+   should send the reply to the server that issued the request.
 
    Example 1.1. secret parameter example
 modparam("auth", "secret", "johndoessecretphrase")
 
-1.4.2. nonce_expire (integer)
+4.2. nonce_expire (integer)
 
-   Nonces have limited lifetime. After a given period of time
-   nonces will be considered invalid. This is to protect replay
-   attacks. Credentials containing a stale nonce will be not
-   authorized, but the user agent will be challenged again. This
-   time the challenge will contain stale parameter which will
-   indicate to the client that it doesn't have to disturb user by
-   asking for username and password, it can recalculate
+   Nonces have limited lifetime. After a given period of time nonces will
+   be considered invalid. This is to protect replay attacks. Credentials
+   containing a stale nonce will be not authorized, but the user agent
+   will be challenged again. This time the challenge will contain stale
+   parameter which will indicate to the client that it doesn't have to
+   disturb user by asking for username and password, it can recalculate
    credentials using existing username and password.
 
    The value is in seconds and default value is 30 seconds.
@@ -170,58 +210,55 @@ modparam("auth", "secret", "johndoessecretphrase")
    Example 1.2. nonce_expire parameter example
 modparam("auth", "nonce_expire", 15)   # Set nonce_expire to 15s
 
-1.4.3. rpid_prefix (string)
+4.3. rpid_prefix (string)
 
-   Prefix to be added to Remote-Party-ID header field just before
-   the URI returned from either radius or database.
+   Prefix to be added to Remote-Party-ID header field just before the URI
+   returned from either radius or database.
 
    Default value is "".
 
    Example 1.3. rpid_prefix parameter example
 modparam("auth", "rpid_prefix", "Whatever <")
 
-1.4.4. rpid_suffix (string)
+4.4. rpid_suffix (string)
 
-   Suffix to be added to Remote-Party-ID header field after the
-   URI returned from either radius or database.
+   Suffix to be added to Remote-Party-ID header field after the URI
+   returned from either radius or database.
 
-   Default value is
-   ";party=calling;id-type=subscriber;screen=yes".
+   Default value is ";party=calling;id-type=subscriber;screen=yes".
 
    Example 1.4. rpid_suffix parameter example
 modparam("auth", "rpid_suffix", "@1.2.3.4>")
 
-1.4.5. realm_prefix (string)
+4.5. realm_prefix (string)
 
-   Prefix to be automatically strip from realm. As an alternative
-   to SRV records (not all SIP clients support SRV lookup), a
-   subdomain of the master domain can be defined for SIP purposes
-   (like sip.mydomain.net pointing to same IP address as the SRV
-   record for mydomain.net). By ignoring the realm_prefix "sip.",
-   at authentication, sip.mydomain.net will be equivalent to
-   mydomain.net .
+   Prefix to be automatically strip from realm. As an alternative to SRV
+   records (not all SIP clients support SRV lookup), a subdomain of the
+   master domain can be defined for SIP purposes (like sip.mydomain.net
+   pointing to same IP address as the SRV record for mydomain.net). By
+   ignoring the realm_prefix "sip.", at authentication, sip.mydomain.net
+   will be equivalent to mydomain.net .
 
    Default value is empty string.
 
    Example 1.5. realm_prefix parameter example
 modparam("auth", "realm_prefix", "sip.")
 
-1.4.6. rpid_avp (string)
+4.6. rpid_avp (string)
 
-   Full AVP specification for the AVP which stores the RPID value.
-   It used to transport the RPID value from authentication backend
-   modules (auth_db or auth_radius) or from script to the auth
-   function append_rpid_hf and is_rpid_user_e164.
+   Full AVP specification for the AVP which stores the RPID value. It used
+   to transport the RPID value from authentication backend modules
+   (auth_db or auth_radius) or from script to the auth function
+   append_rpid_hf and is_rpid_user_e164.
 
-   If defined to NULL string, all RPID functions will fail at
-   runtime.
+   If defined to NULL string, all RPID functions will fail at runtime.
 
    Default value is "$avp(s:rpid)".
 
    Example 1.6. rpid_avp parameter example
 modparam("auth", "rpid_avp", "$avp(i:13)")
 
-1.4.7. username_spec (string)
+4.7. username_spec (string)
 
    This name of the pseudo-variable that will hold the username.
 
@@ -230,7 +267,7 @@ modparam("auth", "rpid_avp", "$avp(i:13)")
    Example 1.7. username_spec parameter usage
 modparam("auth", "username_spec", "$var(username)")
 
-1.4.8. password_spec (string)
+4.8. password_spec (string)
 
    This name of the pseudo-variable that will hold the password.
 
@@ -239,79 +276,82 @@ modparam("auth", "username_spec", "$var(username)")
    Example 1.8. password_spec parameter usage
 modparam("auth", "password_spec", "$avp(s:password)")
 
-1.4.9. calculate_ha1 (integer)
+4.9. calculate_ha1 (integer)
 
-   This parameter tells the server whether it should expect
-   plaintext passwords in the pseudo-variable or a pre-calculated
-   HA1 string.
+   This parameter tells the server whether it should expect plaintext
+   passwords in the pseudo-variable or a pre-calculated HA1 string.
 
-   If the parameter is set to 1 then the server will assume that
-   the "password_spec" pseudo-variable contains plaintext
-   passwords and it will calculate HA1 strings on the fly. If the
-   parameter is set to 0 then the server assumes the
-   pseudo-variable contains the HA1 strings directly and will not
-   calculate them.
+   If the parameter is set to 1 then the server will assume that the
+   "password_spec" pseudo-variable contains plaintext passwords and it
+   will calculate HA1 strings on the fly. If the parameter is set to 0
+   then the server assumes the pseudo-variable contains the HA1 strings
+   directly and will not calculate them.
 
    Default value of this parameter is 0.
 
    Example 1.9. calculate_ha1 parameter usage
 modparam("auth", "calculate_ha1", 1)
 
-1.4.10. nonce_reuse (integer)
+4.10. nonce_reuse (integer)
 
-   Since version 1.4.0, the module checks if the nonce value is
-   re-used, enhancing security protection against reply and man in
-   the middle attacks. This check is done by default.
+   Since version 1.4.0, the module checks if the nonce value is re-used,
+   enhancing security protection against reply and man in the middle
+   attacks. This check is done by default.
 
-   If the parameter is set to 1 then the nonce reuse checking is
-   disabled, offering compatibility with previous behavior. Not
-   recommended though, this functionality is still good in some
-   scenarios, specially when registration time is very low to deal
-   with NAT traversal.
+   If the parameter is set to 1 then the nonce reuse checking is disabled,
+   offering compatibility with previous behavior. Not recommended though,
+   this functionality is still good in some scenarios, specially when
+   registration time is very low to deal with NAT traversal.
 
-   Default value of this parameter is 0 (protect against nonce
-   reuse).
+   Default value of this parameter is 0 (protect against nonce reuse).
 
    Example 1.10. nonce_reuse parameter usage
 modparam("auth", "nonce_reuse", 1)
 
-1.5. Exported Functions
+5. Exported Functions
 
-1.5.1.  www_challenge(realm, qop)
+   5.1. www_challenge(realm, qop)
+   5.2. proxy_challenge(realm, qop)
+   5.3. consume_credentials()
+   5.4. is_rpid_user_e164()
+   5.5. append_rpid_hf()
+   5.6. append_rpid_hf(prefix, suffix)
+   5.7. pv_www_authorize(realm)
+   5.8. pv_proxy_authorize(realm)
 
-   The function challenges a user agent. It will generate a
-   WWW-Authorize header field containing a digest challenge, it
-   will put the header field into a response generated from the
-   request the server is processing and send the reply. Upon
-   reception of such a reply the user agent should compute
-   credentials and retry the request. For more information
-   regarding digest authentication see RFC2617.
+5.1.  www_challenge(realm, qop)
+
+   The function challenges a user agent. It will generate a WWW-Authorize
+   header field containing a digest challenge, it will put the header
+   field into a response generated from the request the server is
+   processing and send the reply. Upon reception of such a reply the user
+   agent should compute credentials and retry the request. For more
+   information regarding digest authentication see RFC2617.
+
+   In case the reply cannot be sent, this method returns "-1"; in case a
+   reply was sent, it just terminates further script processing.
 
    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.
-       If an empty string "" is used then the server will generate
-       it from the request. In case of REGISTER requests To header
-       field domain will be used (because this header field
-       represents a user being registered), for all other messages
-       From header field domain will be used.
+     * 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.
+       If an empty string "" is used then the server will generate it from
+       the request. In case of REGISTER requests To header field domain
+       will be used (because this header field represents a user being
+       registered), for all other messages From header field domain will
+       be used.
        The string may contain pseudo variables.
-     * qop - Value of this parameter can be either "1" or "0".
-       When set to 1 then the server will put a qop parameter in
-       the challenge. When set to 0 then the server will not put
-       the qop parameter in the challenge. It is recommended to
-       use the qop parameter, however there are still some user
-       agents that cannot handle qop properly so we made this
-       optional. On the other hand there are still some user
-       agents that cannot handle request without a qop parameter
-       too.
-       Enabling this parameter don't improve the security at the
-       moment, because the sequence number is not stored and
-       therefore could not be checked. Actually there is no
-       information kept by the module during the challenge and
-       response requests.
+     * qop - Value of this parameter can be either "1" or "0". When set to
+       1 then the server will put a qop parameter in the challenge. When
+       set to 0 then the server will not put the qop parameter in the
+       challenge. It is recommended to use the qop parameter, however
+       there are still some user agents that cannot handle qop properly so
+       we made this optional. On the other hand there are still some user
+       agents that cannot handle request without a qop parameter too.
+       Enabling this parameter don't improve the security at the moment,
+       because the sequence number is not stored and therefore could not
+       be checked. Actually there is no information kept by the module
+       during the challenge and response requests.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -322,39 +362,36 @@ if (!www_authorize("siphub.net", "subscriber")) {
 };
 ...
 
-1.5.2.  proxy_challenge(realm, qop)
+5.2.  proxy_challenge(realm, qop)
 
    The function challenges a user agent. It will generate a
-   Proxy-Authorize header field containing a digest challenge, it
-   will put the header field into a response generated from the
-   request the server is processing and send the reply. Upon
-   reception of such a reply the user agent should compute
-   credentials and retry the request. For more information
-   regarding digest authentication see RFC2617.
+   Proxy-Authorize header field containing a digest challenge, it will put
+   the header field into a response generated from the request the server
+   is processing and send the reply. Upon reception of such a reply the
+   user agent should compute credentials and retry the request. For more
+   information regarding digest authentication see RFC2617.
+
+   In case the reply cannot be sent, this method returns "-1"; in case a
+   reply was sent, it just terminates further script processing.
 
    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.
-       If an empty string "" is used then the server will generate
-       it from the request. From header field domain will be used
-       as realm.
+     * 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.
+       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.
-     * qop - Value of this parameter can be either "1" or "0".
-       When set to 1 then the server will put a qop parameter in
-       the challenge. When set to 0 then the server will not put
-       the qop parameter in the challenge. It is recommended to
-       use the qop parameter, however there are still some user
-       agents that cannot handle qop properly so we made this
-       optional. On the other hand there are still some user
-       agents that cannot handle request without a qop parameter
-       too.
-       Enabling this parameter don't improve the security at the
-       moment, because the sequence number is not stored and
-       therefore could not be checked. Actually there is no
-       information kept by the module during the challenge and
-       response requests.
+     * qop - Value of this parameter can be either "1" or "0". When set to
+       1 then the server will put a qop parameter in the challenge. When
+       set to 0 then the server will not put the qop parameter in the
+       challenge. It is recommended to use the qop parameter, however
+       there are still some user agents that cannot handle qop properly so
+       we made this optional. On the other hand there are still some user
+       agents that cannot handle request without a qop parameter too.
+       Enabling this parameter don't improve the security at the moment,
+       because the sequence number is not stored and therefore could not
+       be checked. Actually there is no information kept by the module
+       during the challenge and response requests.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -365,15 +402,15 @@ if (!proxy_authorize("", "subscriber)) {
 };
 ...
 
-1.5.3.  consume_credentials()
+5.3.  consume_credentials()
 
-   This function removes previously authorized credentials from
-   the message being processed by the server. That means that the
-   downstream message will not contain credentials there were used
-   by this server. This ensures that the proxy will not reveal
-   information about credentials used to downstream elements and
-   also the message will be a little bit shorter. The function
-   must be called after www_authorize or proxy_authorize.
+   This function removes previously authorized credentials from the
+   message being processed by the server. That means that the downstream
+   message will not contain credentials there were used by this server.
+   This ensures that the proxy will not reveal information about
+   credentials used to downstream elements and also the message will be a
+   little bit shorter. The function must be called after www_authorize or
+   proxy_authorize.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -384,14 +421,13 @@ if (www_authorize("", "subscriber)) {
 };
 ...
 
-1.5.4.  is_rpid_user_e164()
+5.4.  is_rpid_user_e164()
 
-   The function checks if the SIP URI received from the database
-   or radius server and will potentially be used in
-   Remote-Party-ID header field contains an E164 number (+followed
-   by up to 15 decimal digits) in its user part. Check fails, if
-   no such SIP URI exists (i.e. radius server or database didn't
-   provide this information).
+   The function checks if the SIP URI received from the database or radius
+   server and will potentially be used in Remote-Party-ID header field
+   contains an E164 number (+followed by up to 15 decimal digits) in its
+   user part. Check fails, if no such SIP URI exists (i.e. radius server
+   or database didn't provide this information).
 
    This function can be used from REQUEST_ROUTE.
 
@@ -402,13 +438,13 @@ if (is_rpid_user_e164()) {
 };
 ...
 
-1.5.5.  append_rpid_hf()
+5.5.  append_rpid_hf()
 
-   Appends to the message a Remote-Party-ID header that contains
-   header 'Remote-Party-ID: ' followed by the saved value of the
-   SIP URI received from the database or radius server followed by
-   the value of module parameter radius_rpid_suffix. The function
-   does nothing if no saved SIP URI exists.
+   Appends to the message a Remote-Party-ID header that contains header
+   'Remote-Party-ID: ' followed by the saved value of the SIP URI received
+   from the database or radius server followed by the value of module
+   parameter radius_rpid_suffix. The function does nothing if no saved SIP
+   URI exists.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE.
@@ -418,21 +454,21 @@ if (is_rpid_user_e164()) {
 append_rpid_hf();  # Append Remote-Party-ID header field
 ...
 
-1.5.6.  append_rpid_hf(prefix, suffix)
+5.6.  append_rpid_hf(prefix, suffix)
 
-   This function is the same as Section 1.5.5, "
-   append_rpid_hf()". The only difference is that it accepts two
-   parameters--prefix and suffix to be added to Remote-Party-ID
-   header field. This function ignores rpid_prefix and rpid_suffix
-   parameters, instead of that allows to set them in every call.
+   This function is the same as Section 5.5, " append_rpid_hf()". The only
+   difference is that it accepts two parameters--prefix and suffix to be
+   added to Remote-Party-ID header field. This function ignores
+   rpid_prefix and rpid_suffix parameters, instead of that allows to set
+   them in every call.
 
    Meaning of the parameters is as follows:
-     * prefix - Prefix of the Remote-Party-ID URI. The string will
-       be added at the begining of body of the header field, just
-       before the URI.
-     * suffix - Suffix of the Remote-Party-ID header field. The
-       string will be appended at the end of the header field. It
-       can be used to set various URI parameters, for example.
+     * prefix - Prefix of the Remote-Party-ID URI. The string will be
+       added at the begining of body of the header field, just before the
+       URI.
+     * suffix - Suffix of the Remote-Party-ID header field. The string
+       will be appended at the end of the header field. It can be used to
+       set various URI parameters, for example.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE.
@@ -443,35 +479,32 @@ append_rpid_hf();  # Append Remote-Party-ID header field
 append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");
 ...
 
-1.5.7.  pv_www_authorize(realm)
+5.7.  pv_www_authorize(realm)
 
    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.
+   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:
-     * -5 (generic error) - some generic error occurred and no
-       reply was sent out;
-     * -4 (no credentials) - credentials were not found in
-       request;
+     * -5 (generic error) - some generic error occurred and no reply was
+       sent out;
+     * -4 (no credentials) - credentials were not found in request;
      * -3 (stale nonce) - stale nonce;
      * -2 (invalid password) - valid user, but wrong password;
      * -1 (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.
-       If an empty string "" is used then the server will generate
-       it from the request. In case of REGISTER requests To header
-       field domain will be used (because this header field
-       represents a user being registered), for all other messages
-       From header field domain will be used.
+     * 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.
+       If an empty string "" is used then the server will generate it from
+       the request. In case of REGISTER requests To header field domain
+       will be used (because this header field represents a user being
+       registered), for all other messages From header field domain will
+       be used.
        The string may contain pseudo variables.
 
    This function can be used from REQUEST_ROUTE.
@@ -485,25 +518,22 @@ if (!pv_www_authorize("kamailio.org")) {
 };
 ...
 
-1.5.8.  pv_proxy_authorize(realm)
+5.8.  pv_proxy_authorize(realm)
 
    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. For more about the
-   negative return codes, see the above function.
+   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. For more
+   about the negative return codes, see the above function.
 
    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.
-       If an empty string "" is used then the server will generate
-       it from the request. From header field domain will be used
-       as realm.
+     * 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.
+       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.

modules_k/auth/challenge.c

@@ -214,7 +214,10 @@ static inline int challenge(struct sip_msg* _msg, gparam_p _realm, int _qop,
 			&auth_hf_len, _qop, _challenge_msg);
 	if (!auth_hf) {
 		LM_ERR("failed to generate nonce\n");
-		return -1;
+		if (send_resp(_msg, 500, &auth_500_err, 0, 0)==-1)
+			return -1;
+		else
+			return 0;
 	}
 
 	reason.s = _message;

modules_k/auth/doc/auth_admin.xml

@@ -295,6 +295,10 @@ modparam("auth", "nonce_reuse", 1)
 		request. For more information regarding digest authentication 
 		see RFC2617.
 		</para>
+		<para>
+		In case the reply cannot be sent, this method returns "-1"; in case a
+		reply was sent, it just terminates further script processing.
+		</para>
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
 		<listitem>
@@ -359,6 +363,10 @@ if (!www_authorize("siphub.net", "subscriber")) {
 		reply the user agent should compute credentials and retry the request.
 		For more information regarding digest authentication see RFC2617.
 		</para>
+		<para>
+		In case the reply cannot be sent, this method returns "-1"; in case a
+		reply was sent, it just terminates further script processing.
+		</para>
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
 		<listitem>