Module: kamailio Branch: master Commit: 8da7ee85d673e544dc4bfd1e6b6c3b69af5d492c URL: https://github.com/kamailio/kamailio/commit/8da7ee85d673e544dc4bfd1e6b6c3b6… Author: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Committer: Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; Date: 2015-03-07T23:02:52+01:00 auth_xkeys: more details about the interaction between sender and receiver --- Modified: modules/auth_xkeys/README Modified: modules/auth_xkeys/doc/auth_xkeys_admin.xml --- Diff: https://github.com/kamailio/kamailio/commit/8da7ee85d673e544dc4bfd1e6b6c3b6… Patch: https://github.com/kamailio/kamailio/commit/8da7ee85d673e544dc4bfd1e6b6c3b6… --- diff --git a/modules/auth_xkeys/README b/modules/auth_xkeys/README index 10785f8..c2cd6aa 100644 --- a/modules/auth_xkeys/README +++ b/modules/auth_xkeys/README @@ -65,7 +65,20 @@ Chapter 1. Admin Guide 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). + (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). diff --git a/modules/auth_xkeys/doc/auth_xkeys_admin.xml b/modules/auth_xkeys/doc/auth_xkeys_admin.xml index 51002cd..2b46674 100644 --- a/modules/auth_xkeys/doc/auth_xkeys_admin.xml +++ b/modules/auth_xkeys/doc/auth_xkeys_admin.xml @@ -23,7 +23,21 @@ 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). + 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. + </para> + <para> + 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. </para> <para> For proper protection, it is recommended to use this