auth 7 auth Basic Functionality for Digest Authentication 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 auth_db, auth_diameter, auth_identity, and auth_radius. Allowed in request processing only. The consume_credentials() 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 www_authenticate. integer 0 The auth_checks_in_dlg parameter controls which integrity checks are performed on requests within a dialog, ie., requests that carry a To tag. The default value of 0 turns off any checks. Otherwise, the value indicates which checks are run. See Additional Integrity Checks below for more details. integer 0 The auth_checks_no_dlg 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 0 turns off any checks. Otherwise, the value indicates which checks are run. See Additional Integrity Checks below for more details. integer 0 The auth_checks_register parameter controls which integrity checks are performed on a REGISTER message. If the parameter is changed from its default value of 0, it activates those checks and defines, which checks are run. See Additional Integrity Checks below for more details. attriubte name $digest_challenge The challenge_attr 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. integer 20 The nc_array_order parameter is an alternative way to set the maximum number of nonces for the nonce check enabled by the nonce_count parameter. Its meaning is identical to that of the nc_array_size parameter but the size is given by stating the power of 2. See nc_array_size and nonce_count for more details. integer 1048576 The nc_array_size parameter sets the maximum number of in-flight nonces for the nonce count check enabled by the nonce_count 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 nonce_count 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 nc_array_order parameter can be used to directly specify the power of 2. For instance, a value for nc_array_order of 20 is equivalent to a nc_array_size of 1048576. The memory used to keep the nonce state will be equal to the value of nc_array_size in bytes. integer 1 The nid_pool_no parameter controls the number of partitions for the nonce_count and one_time_nonce 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 nid_pool_no 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 (nc_array_size for nonce_count and otn_in_flight_no for one_time_nonce) divided by the partitions number (nid_pool_no). 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 nid_pool_no, since the messages will be close to equally distributed to processes using different partitions. The nid_pool_no 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). integer 3 The nonce_auth_max_drift 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 nonce_auth_max_drift 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. boolean no The nonce_count parameter controls, whether tracking of nounce count is enabled. If it is set to yes, the received nc value is remembered and checked against the value used in the previous digest response. For a successful authentication the received nc 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 qop parameter must not be set to an empty string. It it is, the challenges won’t include the qop parameter and the user agent will probably not include the qop or nc parameters in its response. If a response doesn’t include qop or nc (for example obsolete UAs that don't support them) the response will be checked according to the other enabled nonce checks, in this order: one_time_nonce and the applicable of the additional integrity checks. If a response includes nc only the normal nonce_expire checks and the nonce_count checks will be performed, all the other checks will be ignored. The nonce_count checks work by tracking a limited number of nonces. The maximum number of tracked nonces is set using the nc_array_size or nc_array_order 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 nc_array_size, the nonce count check should work flawlessly. For optimal performance (maximum reuse of cache credentials) nc_array_size divided by nid_pool_no should be lower then the message rate multiplied by the desired nonce_expire. The maximum accepted nc value is 255. If nc becomes greater then this, the nonce will be considered stale and the UA will be re-challenged. Note: If the nonce_count 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 t_newtran, to absorb possible retransmissions. All the replies need to be sent statefuly, using t_reply()). 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 tm. An example on how to implement a stateful registrar can be found in registrar. integer 300 The nonce_exipre 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 stale 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. boolean no The one_time_nonce controls whether digist responses with a reused nonce will be rejected. If it is set to yes, 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 t_newtran function. For more information on stateful mode see tm. An example on how to implement a stateful registrar can be found in registrar. 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 nonce_count 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 qop and nc. 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 otn_in_flight_no or otn_in_flight_order 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 otn_in_flight_no, the one time nonce check should work flawlessly. integer 1048576 The otn_in_flight_no parameter specifies the maximum number of in-flight nonces for the one time nonce check enabled by the one_time_nonce 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 one_time_nonce 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 otn_in_flight_order 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 otn_in_flight_no divided by 8 since only 1 bit of state is kept per nonce. integer 20 The otn_in_flight_order parameter is an alternative way to set the maximum number of nonces for the one time nonce check enabled by the one_time_nonce parameter. Its meaning is identical to that of the otn_in_flight_no parameter but the size is given by stating the power of 2. See otn_in_flight_no and one_time_nonce for more details. boolean no If the protect_contacts parameter is set to yes, the contacts are included when creating a nonce. string "Proxy-Authenticate" The proxy_challenge_header parameter contains the name of the header field that should be used to include the proxy-to-user challenge. string "auth" The qop parameter determines, which value for the qop 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 qop 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 auth, only authentication should be done and the response is solely calculated using information from the challenge plus the user’s password. A value of auth-int 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 qop module. It may also be an empty string, in which case no qop 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 nonce_count parameter. See there for more information. string random value The secret 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. string "WWW-Authenticate The www_challenge_header parameter contains the name of the header field that should be used to transmit a user-to-user challenge for authentication. 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 nonce_expire), 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 auth_checks_register sets them for REGISTER requests. The parameter auth_checks_no_dlg does the same for requests that to not have a tag 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 auth_checks_in_dlg 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: 1 check the full Request-URI, 2 check the Call-ID, 4 check the tag parameter of the From header field, 9 check the source IP address the request was received from. For example, setting auth_checks_register to 6 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 secret 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. ser ser.cfg auth_db auth_diameter auth_identity auth_radius