[sr-dev] git:master:8da7ee85: auth_xkeys: more details about the interaction between sender and receiver

[Daniel-Constantin Mierla]

Module: kamailio
Branch: master
Commit: 8da7ee85d673e544dc4bfd1e6b6c3b69af5d492c
URL: https://github.com/kamailio/kamailio/commit/8da7ee85d673e544dc4bfd1e6b6c3b69af5d492c

Author: Daniel-Constantin Mierla <miconda at gmail.com>
Committer: Daniel-Constantin Mierla <miconda at gmail.com>
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/8da7ee85d673e544dc4bfd1e6b6c3b69af5d492c.diff
Patch: https://github.com/kamailio/kamailio/commit/8da7ee85d673e544dc4bfd1e6b6c3b69af5d492c.patch

---

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