Table of Contents
List of Examples
secret parameter usageusername_format parameter
usagesha_algorithm parameter
usageTable of Contents
This module contains all authentication related functions that can work with ephemeral credentials. This module can be used together with the auth module for digest authentication. Use this module if you want to use ephemeral credentials instead of ordinary usernames and passwords.
Ephemeral credentials are generated by a web-service and enforced on Kamailio. This use of ephemeral credentials ensures that access to Kamailio is controlled even if the credentials cannot be kept secret, as can be the case in WebRTC where the credentials may be specified in Javascript.
The only interaction needed between the web-service and Kamailio is to share a secret key.
Credentials will typically be requested from the web-service using an HTTP POST and provided in a HTTP response with a content-type of "application/json". To prevent unauthorised use the HTTP requests can be ACLd by various means.
This mechanism is based on draft-uberti-rtcweb-turn-rest.
The request to the web-service should contain the following parameters:
service - specifies the desired service (msrp, sip, etc)
username - an optional user identifier for the service (as would normally be found in the username parameter of an Authorization: or Proxy-Authorization: header)
key - an optional API key used for authentication
The response should include the following parameters:
username - the username to use, which is a colon-delimited combination of the expiration timestamp and the username parameter from the request (if specified). When used with this module the timestamp must be a UNIX timestamp.
password - the password to use; this value is computed from the secret key and the returned username value, by performing base64(hmac-sha1(secret key, returned username)).
ttl - the duration for which the username and password are valid, in seconds.
uris - an array of URIs indicating servers that the username and password are valid for.
Example 1.2. Response example
{
"username" : "1234567890:foo@bar.com",
"password" : "asdfghjklauio=",
"ttl" : 86400,
"uris" : [
"sip:1.2.3.4;transport=ws",
"sip:5.6.7.8;transport=ws"
]
}
The shared secret to use for generating credentials. This parameter can be set multiple times - this enables the secret used for new credentials to be changed without causing existing credentials to stop working. The last secret set is the first that will be tried.
The format of the username in the web-service response.
0 (deprecated - pre IETF draft format) - <username parameter from the request>:<timestamp>
1 (default - IETF draft format) - <timestamp>:<username parameter from the request>
Example 1.4. username_format parameter
usage
...
modparam("auth_ephemeral", "username_format", 0)
...
This function performs proxy authentication.
This function can only be used when the auth module is loaded before this module.
The meaning of the parameters are as follows:
realm - realm is an opaque string that the user agent should present to the user so that 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 an empty string “”. Apart from a static string, a typical value is the From-URI domain (i.e., $fd).
The string may contain pseudo variables.
This function can be used from REQUEST_ROUTE.
Example 1.6. autheph_proxy usage
...
if (!autheph_proxy("$fd")) {
auth_challenge("$fd", "1");
exit;
}
...
This function performs WWW digest authentication.
This function can only be used when the auth module is loaded before this module.
The meaning of the parameters are as follows:
realm - realm is an opaque string that the user agent should present to the user so that 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 an empty string “”. Apart from a static string, a typical value is the From-URI domain (i.e., $fd).
The string may contain pseudo variables.
method - the method to be used for authentication. This parameter is optional and if not set the first "word" on the request-line is used.
This function can be used from REQUEST_ROUTE.
Example 1.7. autheph_www usage
...
if (!autheph_www("$fd")) {
auth_challenge("$fd", "1");
exit;
}
...
This function combines the functionalities of
autheph_www and
autheph_proxy, the first
being executed if the SIP request is a REGISTER, the second for
the rest.
This function can only be used when the auth module is loaded before this module.
The meaning of the parameters are as follows:
realm - realm is an opaque string that the user agent should present to the user so that 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 an empty string “”. Apart from a static string, a typical value is the From-URI domain (i.e., $fd).
The string may contain pseudo variables.
This function can be used from REQUEST_ROUTE.
Example 1.8. autheph_check usage
...
if (!autheph_check("$fd")) {
auth_challenge("$fd", "1");
exit;
}
...
This function performs non-digest ephemeral authentication. This may be used when digest authentication cannot. For example, during WebSocket handshake the username may be part of the requested URI and the password presented in a Cookie: header.
This function may be used without loading the auth module.
The meaning of the parameters are as follows:
username - the username returned in the response from the web-service.
password - the password returned in the response from the web-service.
This function can be used from REQUEST_ROUTE.
Example 1.9. autheph_authenticate usage
...
if (!autheph_authenticate("$var(username)", "$var(password)")) {
sl_send_reply("403", "Forbidden");
exit;
}
...
This function checks that the username (or username and domain) in the From: URI matches the credentials.
When used without the username parameter it compares the From: URI with the credentials used to authenticate the request (in the Authorization: or Proxy-Authorization: headers).
The username parameter can be used to check the From: when individual SIP requests are not authenticated (for example, when they are over WebSockets and the connection was authenticated during the handshake). In this scenario the username should be cached (perhaps in a hash-table) at the point the authentication occurs.
This function must have the optional username parameter specified to use it without loading the auth module before this module.
The meaning of the parameters are as follows:
username (optional) - the username returned in the response from the web-service.
This function can be used from REQUEST_ROUTE.
Example 1.10. autheph_check_from usage
...
if (!autheph_check_from()) {
sl_send_reply("403", "Forbidden");
exit;
}
...
This function checks that the username (or username and domain) in the To: URI matches the credentials.
When used without the username parameter it compares the To: URI with the credentials used to authenticate the request (in the Authorization: or Proxy-Authorization: headers).
The username parameter can be used to check the From: when individual SIP requests are not authenticated (for example, when they are over WebSockets and the connection was authenticated during the handshake). In this scenario the username should be cached (perhaps in a hash-table) at the point the authentication occurs.
This function must have the optional username parameter specified to use it without loading the auth module before this module.
The meaning of the parameters are as follows:
username (optional) - the username returned in the response from the web-service.
This function can be used from REQUEST_ROUTE.
Example 1.11. autheph_check_to usage
...
if (!autheph_check_to()) {
sl_send_reply("403", "Forbidden");
exit;
}
...
This function checks that the timestamp in the username parameter has not expired. The autheph_(check|proxy|www) functions all do this automatically, but in a scenario when individual SIP requests are not authenticated (for example, when they are over WebSockets and the connection was authenticated during the handshake) you may want to re-check for each new out-of-dialog request. In this scenario the username should be cached (perhaps in a hash-table) at the point authentication occurs.
This function may be used without loading the auth module.
The meaning of the parameters are as follows:
username - the username returned in the response from the web-service.
This function can be used from REQUEST_ROUTE.
Example 1.12. autheph_check_timestamp usage
...
if (!autheph_check_timestamp("$var(username)")) {
sl_send_reply("403", "Forbidden");
exit;
}
...
Add a secret to the head of the shared secret list. The secret will be the first one tried during future authentication attempts. This command allows you to update the shared secret list without having to restart Kamailio.
If you want your new shared secret list to persist across restarts you must add it to your Kamailio configuration file.
Name: autheph.add_secret
Parameters:
secret
RPC Command Example:
... kamcmd autheph.add_secret mysecret
Dump the set of shared secrets.
Name: autheph.dump_secrets
Parameters:
none
RPC Command Example:
... kamcmd autheph.dump_secrets ...
Remove the secret with the specified integer ID. This command allows you to update the shared secret list without having to restart Kamailio.
If you want your new shared secret list to persist across restarts you must add it to your Kamailio configuration file.
Name: autheph.rm_secret
Parameters:
ID - the ID of the secret to remove
RPC Command Example:
... kamcmd autheph.rm_secret 0 ...