Table of Contents
List of Examples
xkey parameterauth_xkeys_add usageauth_xkeys_check usageTable of Contents
This module provides a custom mechanism to authenticate a SIP entity using a list of shared keys.
It is similar to the API key based authentication used by many web services. In short, the sender adds a particular header with a hash token computed with the shared key and some values from the SIP request (e.g., local IP, From/To/R-URI username, Call-ID, CSeq). The receiver will check the hash value and decide whether the SIP message is authenticated or not. The sender and receiver have to agree beforehand on the name of the server, shared secret, algorithm to be used and what data is going to be hashed.
The module is designed to work with many shared keys on the same group, for more flexibility in adding/removing keys. The last added key in the group is used to add the header, but older ones are used for matching the hash value. That allows to change the active shared key without affecting ongoing traffic. If one decides to use a new share key, add it first to receiver (it will still authenticate with older key) and then to the sender. Once both nodes are provisioned with the new key, the older one can be removed.
For proper protection, it is recommended to use this authentication mechanism over a secure channel (e.g., TLS, VPN, private network).
The benefit is avoiding the extra traffic and processing required by WWW-Digest authentication schema (no more 401/407 and a follow up request with credentials).
Another goal is to provide more elasticity for scalability needs of the core SIP network nodes. Most of the nodes in the core network or the interconnecting peers trust each other based on IP address. But adding a new node requires updates to the exiting ones to trust the IP address of the new node. On large deployments, that can become rather complex. For example, as a replacement for IP trust relationships, the sender can hash the local IP with the secret shared key, add it in the header and the receiver will check if the source ip hased with the key results in the same value.
Not being a challenge-reply mechanism, this can be used to authenticate SIP responses from trusted peers.
Specify the attributes for a shared secret. The value is in the format 'name1=value1;name2=value2;...'. The attributes can be:
id - the id of the group for keys
name - the name of the key within group
value - the value of the key
expires - expiration time (seconds)
Default value is empty.
Example 1.1. Set xkey parameter
...
modparam("auth_xkeys", "xkey", "id=abc;name=xyz;value=secret;expires=72000")
...
Add a header computed with the first key in the group kid, hasing with algorithm alg over the content of parameter data. The parameters can include variables.
The algorithm can be: sha256, sha384, sha512.
This function can be used from ANY_ROUTE.
Example 1.2. auth_xkeys_add usage
...
auth_xkeys_add("X-My-Key", "abc", "sha256", "$Ri:$fu:$ru:$hdr(CSeq)");
...
Check if the value of header hdr matches the value computed with the first key in the group kid, hasing with algorithm alg over the content of parameter data. The parameters can include variables.
The algorithm can be: sha256, sha384, sha512.
Note that the header is not removed by the function, it is recommended to remove it if sending to untrusted destination.
This function can be used from ANY_ROUTE.
Example 1.3. auth_xkeys_check usage
...
if(!auth_xkeys_check("X-My-Key", "abc", "sha256", "$si:$fu:$ru:$hdr(CSeq)")) {
send_reply("403", "Forbidden");
exit;
}
remove_hf("X-My-Key");
...