Auth_ephemeral Module

Peter Dunkley

   Crocodile RCS Ltd
   <peter.dunkley@crocodile-rcs.com>

Carsten Bock

   ng-voice GmbH
   <carsten@ng-voice.com>

   Copyright © 2013 Crocodile RCS Ltd

   Copyright © 2017 ng-voice GmbH
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview

              1.1. How ephemeral credentials work

                    1.1.1. Request
                    1.1.2. Response

        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. secret (string)
              3.2. username_format (integer)
              3.3. sha_algorithm (integer)

        4. Functions

              4.1. autheph_proxy(realm)
              4.2. autheph_www(realm[, method])
              4.3. autheph_check(realm)
              4.4. autheph_authenticate(username, password)
              4.5. autheph_check_from([username])
              4.6. autheph_check_to([username])
              4.7. autheph_check_timestamp(username)

        5. RPC Commands

              5.1. autheph.add_secret
              5.2. autheph.dump_secrets
              5.3. autheph.rm_secret

   List of Examples

   1.1. Request example
   1.2. Response example
   1.3. secret parameter usage
   1.4. username_format parameter usage
   1.5. sha_algorithm parameter usage
   1.6. autheph_proxy usage
   1.7. autheph_www usage
   1.8. autheph_check usage
   1.9. autheph_authenticate usage
   1.10. autheph_check_from usage
   1.11. autheph_check_to usage
   1.12. autheph_check_timestamp usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview

        1.1. How ephemeral credentials work

              1.1.1. Request
              1.1.2. Response

   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. secret (string)
        3.2. username_format (integer)
        3.3. sha_algorithm (integer)

   4. Functions

        4.1. autheph_proxy(realm)
        4.2. autheph_www(realm[, method])
        4.3. autheph_check(realm)
        4.4. autheph_authenticate(username, password)
        4.5. autheph_check_from([username])
        4.6. autheph_check_to([username])
        4.7. autheph_check_timestamp(username)

   5. RPC Commands

        5.1. autheph.add_secret
        5.2. autheph.dump_secrets
        5.3. autheph.rm_secret

1. Overview

   1.1. How ephemeral credentials work

        1.1.1. Request
        1.1.2. Response

   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.

1.1. How ephemeral credentials work

   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.

1.1.1. Request

   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

   Example 1.1. Request example
POST /?service=sip&username=foo@bar.com

1.1.2. Response

   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"
  ]
}

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The module must be loaded before this module:
     * auth (optional).

2.2. External Libraries or Applications

   The following libraries must be installed before running Kamailio with
   this module loaded:
     * OpenSSL.

3. Parameters

   3.1. secret (string)
   3.2. username_format (integer)
   3.3. sha_algorithm (integer)

3.1. secret (string)

   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.

   Example 1.3. secret parameter usage
...
modparam("auth_ephemeral", "secret", "kamailio_rules")
...

3.2. username_format (integer)

   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)
...

3.3. sha_algorithm (integer)

   The SHA algorithm to be used for the Hash.

     * 0 - SHA1 (default, as per IETF/RFC)
     * 1 - SHA256
     * 2 - SHA384
     * 3 - SHA512

   Example 1.5. sha_algorithm parameter usage
...
modparam("auth_ephemeral", "sha_algorithm", 2)
...

4. Functions

   4.1. autheph_proxy(realm)
   4.2. autheph_www(realm[, method])
   4.3. autheph_check(realm)
   4.4. autheph_authenticate(username, password)
   4.5. autheph_check_from([username])
   4.6. autheph_check_to([username])
   4.7. autheph_check_timestamp(username)

4.1.  autheph_proxy(realm)

   This function performs proxy authentication.

Note

   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;
}
...

4.2.  autheph_www(realm[, method])

   This function performs WWW digest authentication.

Note

   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;
}
...

4.3.  autheph_check(realm)

   This function combines the functionalities of autheph_www and
   autheph_proxy, the first being exectuted if the SIP request is a
   REGISTER, the second for the rest.

Note

   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;
}
...

4.4.  autheph_authenticate(username, password)

   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.

Note

   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;
}
...

4.5.  autheph_check_from([username])

   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.

Note

   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;
}
...

4.6.  autheph_check_to([username])

   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.

Note

   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;
}
...

4.7.  autheph_check_timestamp(username)

   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.

Note

   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;
}
...

5. RPC Commands

   5.1. autheph.add_secret
   5.2. autheph.dump_secrets
   5.3. autheph.rm_secret

5.1. autheph.add_secret

   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.

Note

   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

5.2. autheph.dump_secrets

   Dump the set of shared secrets.

   Name: autheph.dump_secrets

   Parameters:
     * none

   RPC Command Example:
...
kamcmd autheph.dump_secrets
...

5.3. autheph.rm_secret

   Remove the secret with the specified integer ID. This command allows
   you to update the shared secret list without having to restart
   Kamailio.

Note

   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
...
