auth(7)

NAME
auth - Basic Functionality for Digest Authentication

DESCRIPTION
The auth SER module provides basic functionality for digest authentication. However, it does not provide access to the user information and therefore relies on another module. These modules are \FCauth_db\F[](7), \FCauth_diameter\F[](7), \FCauth_identity\F[](7), and \FCauth_radius\F[](7).

FUNCTIONS

  consume_credentials ()
Allowed in request processing only.

The \FCconsume_credentials()\F[] function removes previously authorized credentials from the request. This means that forwarded or relayed requests will not contain credentials that were checked by this server and ensures that the proxy will not reveal information about credentials used to downstream elements. In addition, the message will be shorter.

The function must be called after a call to an authorization function such as \FCwww_authenticate\F[]().

MODULE PARAMETERS

  auth_checks_in_dlg
Type: integer
Default: 0

The \FCauth_checks_in_dlg\F[] parameter controls which integrity checks are performed on requests within a dialog, ie., requests that carry a To tag. The default value of \FC0\F[] turns off any checks. Otherwise, the value indicates which checks are run.

See Additional Integrity Checks below for more details.

  auth_checks_no_dlg
Type: integer
Default: 0

The \FCauth_checks_no_dlg\F[] parameter controls which integrity checks are performed on out-of-dialog requests, ie., requests that do not carry a To tag. The default value of \FC0\F[] turns off any checks. Otherwise, the value indicates which checks are run.

See Additional Integrity Checks below for more details.

  auth_checks_register
Type: integer
Default: 0

The \FCauth_checks_register\F[] parameter controls which integrity checks are performed on a REGISTER message. If the parameter is changed from its default value of \FC0\F[], it activates those checks and defines, which checks are run.

See Additional Integrity Checks below for more details.

  challenge_attr
Type: attriubte name
Default: $digest_challenge

The \FCchallenge_attr\F[] parameter names the attribute which will contain the complete header field with the authentication challenge. The content if this attribute has to be added to the response in order to transmit the challenge to the client.

  nc_array_order
Type: integer
Default: 20

The \FCnc_array_order\F[] parameter is an alternative way to set the maximum number of nonces for the nonce check enabled by the \FCnonce_count\F[] parameter. Its meaning is identical to that of the \FCnc_array_size\F[] parameter but the size is given by stating the power of 2. See \FCnc_array_size\F[] and \FCnonce_count\F[] for more details.

  nc_array_size
Type: integer
Default: 1048576

The \FCnc_array_size\F[] parameter sets the maximum number of in-flight nonces for the nonce count check enabled by the \FCnonce_count\F[] parameter. It represents the maximum number of nonces for which state will be kept. When this number is exceeded, state for older nonces will be discarded to make space for new ones. See \FCnonce_count\F[] for more details.

The value should be a power of 2. If it is not, it will be rounded down to such a number. For example a value of 1000000 will be rounded down to 524288. The \FCnc_array_order\F[] parameter can be used to directly specify the power of 2. For instance, a value for \FCnc_array_order\F[] of 20 is equivalent to a \FCnc_array_size\F[] of 1048576.

The memory used to keep the nonce state will be equal to the value of \FCnc_array_size\F[] in bytes.

  nid_pool_no
Type: integer
Default: 1

The \FCnid_pool_no\F[] parameter controls the number of partitions for the \FCnonce_count\F[] and \FCone_time_nonce\F[] arrays. It is common to both of them to reduce the nonce size.

Instead of using single arrays for keeping nonce state, these arrays can be divided into several partitions. Each SER process is assigned to one of these partitions, allowing for higher concurrency on multi-CPU machines. Besides increasing performance, increasing \FCnid_pool_no\F[] has also a negative effect: it could decrease the maximum supported in-flight nonces in certain conditions. In the worst case, when only one SER process receives most of the traffic (e.g. very busy TCP connection between two proxies), the in-flight nonces could be limited to the array size (\FCnc_array_size\F[] for \FCnonce_count\F[] and \FCotn_in_flight_no\F[] for \FCone_time_nonce\F[]) divided by the partitions number (\FCnid_pool_no\F[]). However for normal traffic, where the process receiving a message is either random or chosen in a round-robin fashion, the maximum number of in-flight nonces will be influenced to a very small degree by \FCnid_pool_no\F[], since the messages will be close to equally distributed to processes using different partitions.

The \FCnid_pool_no\F[] value should be one of: 1, 2, 4, 8, 16, 32 or 64 (the maximum value is 64 and all values should be a power of 2 or else they will be rounded down to such a value).

  nonce_auth_max_drift
Type: integer
Default: 3

The \FCnonce_auth_max_drift\F[] parameter specifies the maximum difference in seconds between a nonce creation time and the current time, if the nonce creation time appears to be in the future.

In some cases, like shortly after a system time backward adjustment or when the current proxy is part of a cluster which is not time-synchronized, it's possible to receive a nonce with a creation time in the future. In this case if the difference is greater then the value of \FCnonce_auth_max_drift\F[] in seconds, the nonce is considered stale and the request re-challenged. If this were not done, a dramatic time change backwards may lead to nonces having been generated before the cange being valid for too long.

  nonce_count
Type: boolean
Default: no

The \FCnonce_count\F[] parameter controls, whether tracking of nounce count is enabled. If it is set to \FCyes\F[], the received \FCnc\F[] value is remembered and checked against the value used in the previous digest response. For a successful authentication the received \FCnc\F[] must be greater then the previously received one (See RFC 2617 for more details). This will provide protection against replay attacks while still allowing credentials caching at the UA side.

In order for this to work, the \FCqop\F[] parameter must not be set to an empty string. It it is, the challenges won’t include the \FCqop\F[] parameter and the user agent will probably not include the \FCqop\F[] or \FCnc\F[] parameters in its response.

If a response doesn’t include \FCqop\F[] or \FCnc\F[] (for example obsolete UAs that don't support them) the response will be checked according to the other enabled nonce checks, in this order: \FCone_time_nonce\F[] and the applicable of the additional integrity checks. If a response includes \FCnc\F[] only the normal \FCnonce_expire\F[] checks and the \FCnonce_count\F[] checks will be performed, all the other checks will be ignored.

The \FCnonce_count\F[] checks work by tracking a limited number of nonces. The maximum number of tracked nonces is set using the \FCnc_array_size\F[] or \FCnc_array_order\F[] parameters. If this number is exceeded, older entries will be overwritten. As long as the maximum rate of challengeable messages per average response time is lower then \FCnc_array_size\F[], the nonce count check should work flawlessly. For optimal performance (maximum reuse of cache credentials) \FCnc_array_size\F[] divided by \FCnid_pool_no\F[] should be lower then the message rate multiplied by the desired \FCnonce_expire\F[].

The maximum accepted \FCnc\F[] value is 255. If \FCnc\F[] becomes greater then this, the nonce will be considered stale and the UA will be re-challenged.

Note: If the \FCnonce_count\F[] parameter is enabled, all challenges should be done in stateful mode, ie., a transaction should be created prior to the authentication check, for instance by using the function \FCt_newtran\F[](), to absorb possible retransmissions. All the replies need to be sent statefuly, using \FCt_reply()\F[]()). Otherwise, all retransmissions will be challenged which may cause the user agent to believe the password supplied by the user to be wrong.

For more information on stateful processing, see \FCtm\F[](7). An example on how to implement a stateful registrar can be found in \FCregistrar\F[](7).

  nonce_expire
Type: integer
Default: 300

The \FCnonce_exipre\F[] parameter determines the time in seconds before a nonce is considered stale.

Nonces have a limited lifetime after which they will be considered stale. This is to protect replay attacks. Credentials containing a stale nonce will be not authorized. The user agent will be challenged again instead. This new challenge will not only contain a newly generated nonce, but also the \FCstale\F[] parameter which indicates to the client the failure was not due to a wrong username or password and it doesn't need to disturb the user asking for them. It can simply recalculate its answer using existing username and password.

  one_time_nonce
Type: boolean
Default: no

The \FCone_time_nonce\F[] controls whether digist responses with a reused nonce will be rejected. If it is set to \FCyes\F[], nonces cannot be reused by user agents.

This results in each request being challenged. To avoid retransmits being challenged, it should only be used in stateful mode, ie., by creating a transaction before authentication, for instance trough a call to the \FCt_newtran\F[]() function. For more information on stateful mode see \FCtm\F[](7). An example on how to implement a stateful registrar can be found in \FCregistrar\F[](7).

The one time nonce provides enhanced replay protections at the cost of invalidating UA side credentials caching and causing extra round trips. Therefore, the nonce chount check enabled through the \FCnonce_count\F[] parameter should be preferred.

The one time nonce provides the same protection as the nonce count check but requiring more messages. The advantages are that it uses less memory for the same supported number of maximum in-flight nonces (by a factor of 8) and that it works with user agents that do not support \FCqop\F[] and \FCnc\F[]. It shoud thus be used if such user agents are in use and the checks described in section Additional Integrity Checks are not deemed sufficient.

Like the nonce count check, one time nonces works by tracking a limited number of nonces. The maximum number of tracked nonces is set using the \FCotn_in_flight_no\F[] or \FCotn_in_flight_order\F[] parameters. If this number is exceeded, older entries will be overwritten. As long as the maximum rate of challengeable messages per average response time is lower then \FCotn_in_flight_no\F[], the one time nonce check should work flawlessly.

  otn_in_flight_no
Type: integer
Default: 1048576

The \FCotn_in_flight_no\F[] parameter specifies the maximum number of in-flight nonces for the one time nonce check enabled by the \FCone_time_nonce\F[] parameter. It represents the maximum number of nonces remembered for the one time nonce check. When this number is exceeded, information about older nonces will be discarded and overwritten with information about newly generated nonces. See \FCone_time_nonce\F[] for more details.

The value should be a power of 2. If it is not, it will be rounded down to such a value. The \FCotn_in_flight_order\F[] parameter can be used to directly specify the power of 2.

The memory used to keep the nonce information will be identical to the value of \FCotn_in_flight_no\F[] divided by 8 since only 1 bit of state is kept per nonce.

  otn_in_flight_order
Type: integer
Default: 20

The \FCotn_in_flight_order\F[] parameter is an alternative way to set the maximum number of nonces for the one time nonce check enabled by the \FCone_time_nonce\F[] parameter. Its meaning is identical to that of the \FCotn_in_flight_no\F[] parameter but the size is given by stating the power of 2. See \FCotn_in_flight_no\F[] and \FCone_time_nonce\F[] for more details.

  protect_contacts
Type: boolean
Default: no

If the \FCprotect_contacts\F[] parameter is set to \FCyes\F[], the contacts are included when creating a nonce.

  proxy_challenge_header
Type: string
Default: "Proxy-Authenticate"

The \FCproxy_challenge_header\F[] parameter contains the name of the header field that should be used to include the proxy-to-user challenge.

  qop
Type: string
Default: "auth"

The \FCqop\F[] parameter determines, which value for the \FCqop\F[] parameter should be included in a challenge. The parameter was optional in the SIP revision described by RFC 2543. The current version from RFC 3261 states, however, that the parameter must be included in all challenges.

In digest authentication, the \FCqop\F[] parameter, short for ‘quality of protection’, indicates which parts of a request should be used for the calculation of the digest response. If the value is \FCauth\F[], only authentication should be done and the response is solely calculated using information from the challenge plus the user’s password. A value of \FCauth-int\F[] indicates that in addition the integrity of the request body is to be verified. For this purpose, a hash over the body is additionally included in the calculation.

In a challenge the parameter indicates, which of these methods the server supports. This can either be one of them or both, separated by a comma. For challenges generated by SER, this is given by the \FCqop\F[] module. It may also be an empty string, in which case no \FCqop\F[] parameter will be present in challenges created by SER. This may be necessary for compatibility with some old clients but will make your SER not comply with RFC 3261.

Protection against nonce replay attacks can be achieved by additionally enabling the \FCnonce_count\F[] parameter. See there for more information.

  secret
Type: string
Default: random value

The \FCsecret\F[] parameter sets the secret used for the calculation of the nonce and for message integrity checks. If not set, a random secret will be chosen upon start.

  www_challenge_header
Type: string
Default: "WWW-Authenticate

The \FCwww_challenge_header\F[] parameter contains the name of the header field that should be used to transmit a user-to-user challenge for authentication.

ADDITIONAL INTEGRITY CHECKS
The auth module can perform additional integrity checks on the authentication response inclued in a request by the client.

Without the extra checks, the nonce value will be used only to store the expire time (see \FCnonce_expire\F[]), plus an MD5 hash over it and some secret to prevent tampering with the expire time. With this arrangement, some replay attacks are still possible in the expire "window".

A possible workaround is to always force qop authentification and always check the URI from the authorization header, but this does not work if an upstream proxy rewrites the URI and it will also not work with a lot of UA implementations.

When the extra checks are enabled, the nonce will include and extra MD5 hash over some selected parts of the message and another secret. This will be used to check if these parts of the message are the same when a UA retries the request with the authentication response, thus protecting from replay attacks or at least severly limiting their possibility.

Three module parameters control which parts of the message will be included for different types of requests. The parameter \FCauth_checks_register\F[] sets them for REGISTER requests. The parameter \FCauth_checks_no_dlg\F[] does the same for requests that to not have a \FCtag\F[] parameter in the To header field or have no To header field altogether (in other words requests sent outside of an existing dialog). And, finally, the parameter \FCauth_checks_in_dlg\F[] controls the checks for SIP requests sent within dialogs, such as BYEs or re-INVITEs.

The default value for all three parameters is 0, in which case no extra checks are performed and the module behaves as it did before their introduction. Otherwise the parameter is a bit field. The message parts to be included in the check can be determined by adding any of the following values together:

\FC1\F[]
    check the full Request-URI,

\FC2\F[]
    check the Call-ID,

\FC4\F[]
    check the \FCtag\F[] parameter of the From header field,

\FC9\F[]
    check the source IP address the request was received from.

For example, setting \FCauth_checks_register\F[] to \FC6\F[] would check if the Call-ID or the From tag have changed from the REGISTER message for which the nonce was generated. This allows nonce reuse only within the same UA and for the expire time. Note that enabling the extra checks will limit nonce caching by UAs, requiring extra challenges and round trips, but will provide much better protection.

When the \FCsecret\F[] parameter is set and the extra checks are enabled, the first half of the secret will be used for the expire time hash and the other half for the hash on the extra checks, so make sure you have a long secret. At least 32 characterss are recommended.

SEE ALSO
\FCser\F[](8), \FCser.cfg\F[](5), \FCauth_db\F[](7), \FCauth_diameter\F[](7), \FCauth_identity\F[](7), \FCauth_radius\F[](7)