# Functions

## `consume_credentials()`

This function removes previously authorized credential headers 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`, `proxy_authorize`, `www_authenticate` or `proxy_authenticate`.

### consume_credentials example

    ...
    if (www_authenticate("realm", "subscriber")) {
        consume_credentials();
    }
    ...

## `has_credentials(realm)`

This function returns true if the request has Authorization or Proxy-Authorization header with provided realm. The parameter can be string with pseudo-variables.

### consume_credentials example

    ...
    if (has_credentials("myrealm")) {
        ...
    }
    ...

## `www_challenge(realm, flags)`

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 401 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. See module parameter force_stateless_reply regarding sending of the reply.

Meaning of the parameters is as follows:

- realm - Realm is an 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.

  It must not be empty string . In case of REGISTER requests, the To header field domain (e.g., variable $td) can be used (because this header field represents the user being registered), for all other messages From header field domain can be used (e.g., variable $fd).

  The string may contain pseudo variables.

- flags - Value of this parameter can be a bitmask of following:

  - 1 - build challenge header with qop=auth

  - 2 - build challenge header with qop=auth-int

  - 4 - do not send '500 Internal Server Error' reply automatically in failure cases (error code is returned to config)

  - 16 - build challenge header with stale=true

This function can be used from REQUEST_ROUTE.

### www_challenge usage

    ...
    if (!www_authenticate("$td", "subscriber")) {
    	www_challenge("$td", "1");
    	exit;
    }
    ...

## `proxy_challenge(realm, flags)`

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 407 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. See module parameter force_stateless_reply regarding sending of the reply.

Meaning of the parameters is the same as for function www_challenge(realm, flags)

This function can be used from REQUEST_ROUTE.

### proxy_challenge usage

    ...
    if (!proxy_authenticate("$fd", "subscriber")) {
    	proxy_challenge("$fd", "1");
    	exit;
    }
    ...

## `auth_challenge(realm, flags)`

The function challenges a user agent for authentication. It combines the functions www_challenge() and proxy_challenge(), by calling internally the first one for REGISTER requests and the second one for the rest of other request types. In other words, it challenges for authentication by sending a 401 reply for REGISTER requests and 407 reply for the other types of SIP requests.

Meaning of the parameters the same as for function www_challenge(realm, flags)

This function can be used from REQUEST_ROUTE.

### auth_challenge usage

    ...
    if (!auth_check("$fd", "subscriber", "1")) {
    	auth_challenge("$fd", "1");
    	exit;
    }
    ...

## `pv_www_authenticate(realm, passwd, flags [, method])`

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.

Negative codes may be interpreted as follows:

- -1 (generic error) - some generic error occurred and no reply was sent out

- -2 (invalid password) - wrong password

- -4 (nonce expired) - the nonce has expired

- -5 (no credentials) - request does not contain an Authorization header with the correct realm

- -6 (nonce reused) - the nonce has already been used to authenticate a previous request

Meaning of the parameters is as follows:

- realm - Realm is an 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.

  It must not be empty string . In case of REGISTER requests To header field domain (e.g., variable $td) can be used (because this header field represents a user being registered), for all other messages From header field domain can be used (e.g., variable $fd).

  The string may contain pseudo variables.

- passwd - the password to be used for authentication. Can contain config variables. The Username is taken from Auth header.

- flags - the value of this parameter can be a bitmask of following:

  - 1 - the value of password parameter is HA1 format

  - 2 - build challenge header with no qop and add it to avp

  - 4 - build challenge header with qop=auth and add it to avp

  - 8 - build challenge header with qop=auth-int and add it to avp

  - 16 - build challenge header with stale=true

  - 32 - don't invalidate nc on authentication failure

- method - the method to be used for authentication. This parameter is optional and if not set is the first "word" on the request-line.

When challenge header is built and stored in avp, append_to_reply() and the sl reply functions can be used to send appropriate SIP reply to challenge for authentication.

This function can be used from REQUEST_ROUTE.

### `pv_www_authenticate` usage

    ...
    if (!pv_www_authenticate("$td", "123abc", "0")) {
    	www_challenge("$td", "1");
    	exit;
    }
    ...

## `pv_proxy_authenticate(realm, passwd, flags)`

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.

Meaning of the parameters is the same as for pv_www_authenticate(realm, passwd, flags)

This function can be used from REQUEST_ROUTE.

### pv_proxy_authenticate usage

    ...
    $avp(password)="xyz";
    if (!pv_proxy_authenticate("$fd", "$avp(password)", "0")) {
    	proxy_challenge("$fd", "1");
    	exit;
    }
    ...

## `pv_auth_check(realm, passwd, flags, checks)`

The function combines the functionalities of `pv_www_authenticate` and `pv_proxy_authenticate`, first being executed if the SIP request is a REGISTER, the second for the rest.

Meaning of the first three parameters is the same as for pv_www_authenticate(realm, passwd, flags).

Parameter checks can be used to control the behaviour of the function. If it is 1, then the function will check to see if the authentication username matches either To or From header username, a matter of whether it is for a REGISTER request or not. The parameter may be a pseudo variable.

The set of possible return codes is the same than pv_{www,proxy}_authenticate, with one more possible value:

-8 (auth user mismatch) - the auth user is different than the From/To user

This function can be used from REQUEST_ROUTE.

### pv_auth_check usage

    ...
    $avp(password)="xyz";
    if (!pv_auth_check("$fd", "$avp(password)", "0", "1")) {
    	auth_challenge("$fd", "1");
    	exit;
    }
    ...

## `auth_get_www_authenticate(realm, flags, pvdest)`

Build WWW-Authentication header and set the resulting value in 'pvdest' pseudo-variable parameter.

Meaning of the realm and flags parameters is the same as for pv_www_authenticate(realm, passwd, flags)

This function can be used from ANY_ROUTE.

### auth_get_www_authenticate usage

    ...
    if (auth_get_www_authenticate("$fd", "0", "$var(wauth)")) {
    	xlog("www authenticate header is [$var(wauth)]\n");
    }
    ...

## `auth_algorithm(algorithm)`

Set hash algorithm used for digest authentication thus overriding algorithm parameter. Possible values are the same as those of algorithm parameter. The parameter may be a pseudo variable.

### auth_algorithm example

    ...
    if($fU == "alice") {
        $var(alg) = "SHA-256";
    } else {
        $var(alg) = "MD5";
    }
    auth_algorithm("$var(alg)");
    if (!auth_check("$fd", "subscriber", "1")) {
        auth_challenge("$fd", "1");
        exit;
    }
    ...