Skip to content

Commit f421b33

Browse files
LarryLaffer-devLarryLaffer-dev
authored
Merge pull request #34 from LarryLaffer-dev/auth_aka_cluster
Auth aka cluster
2 parents 1005a49 + 89e5089 commit f421b33

File tree

5 files changed

+649
-75
lines changed

5 files changed

+649
-75
lines changed

‎modules/auth_aka/README‎

Lines changed: 133 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -8,50 +8,52 @@ Auth_aka Module
88
1.1. Overview
99
1.2. Authentication Vectors
1010
1.3. Supported algorithms
11-
1.4. Dependencies
11+
1.4. Clustering / Multi-Node Support
12+
1.5. Dependencies
1213

13-
1.4.1. OpenSIPS Modules
14-
1.4.2. External Libraries or Applications
14+
1.5.1. OpenSIPS Modules
15+
1.5.2. External Libraries or Applications
1516

16-
1.5. Exported Parameters
17+
1.6. Exported Parameters
1718

18-
1.5.1. default_av_mgm (string)
19-
1.5.2. default_qop (string)
20-
1.5.3. default_algorithm (string)
21-
1.5.4. hash_size (integer)
22-
1.5.5. sync_timeout (integer)
23-
1.5.6. async_timeout (integer)
24-
1.5.7. unused_timeout (integer)
25-
1.5.8. unused_timeout (integer)
19+
1.6.1. default_av_mgm (string)
20+
1.6.2. default_qop (string)
21+
1.6.3. default_algorithm (string)
22+
1.6.4. hash_size (integer)
23+
1.6.5. sync_timeout (integer)
24+
1.6.6. async_timeout (integer)
25+
1.6.7. unused_timeout (integer)
26+
1.6.8. pending_timeout (integer)
27+
1.6.9. cachedb_url (string)
2628

27-
1.6. Exported Functions
29+
1.7. Exported Functions
2830

29-
1.6.1. aka_www_authorize([realm]])
30-
1.6.2. aka_proxy_authorize([realm]])
31-
1.6.3. aka_www_challenge([av_mgm[, realm[ ,qop[,
31+
1.7.1. aka_www_authorize([realm]])
32+
1.7.2. aka_proxy_authorize([realm]])
33+
1.7.3. aka_www_challenge([av_mgm[, realm[ ,qop[,
3234
alg]]]])
3335

34-
1.6.4. aka_proxy_challenge([realm]])
35-
1.6.5. aka_av_add(public_identity, private_identity,
36+
1.7.4. aka_proxy_challenge([realm]])
37+
1.7.5. aka_av_add(public_identity, private_identity,
3638
authenticate, authorize,
3739
confidentiality_key, integrity_key[,
3840
algorithms])
3941

40-
1.6.6. aka_av_drop(public_identity,
42+
1.7.6. aka_av_drop(public_identity,
4143
private_identity, authenticate)
4244

43-
1.6.7. aka_av_drop_all(public_identity,
45+
1.7.7. aka_av_drop_all(public_identity,
4446
private_identity[, count])
4547

46-
1.6.8. aka_av_fail(public_identity,
48+
1.7.8. aka_av_fail(public_identity,
4749
private_identity[, count])
4850

49-
1.7. Exported MI Functions
51+
1.8. Exported MI Functions
5052

51-
1.7.1. aka_av_add
52-
1.7.2. aka_av_drop
53-
1.7.3. aka_av_drop_all
54-
1.7.4. aka_av_fail
53+
1.8.1. aka_av_add
54+
1.8.2. aka_av_drop
55+
1.8.3. aka_av_drop_all
56+
1.8.4. aka_av_fail
5557

5658
2. Contributors
5759

@@ -79,18 +81,19 @@ Auth_aka Module
7981
1.6. async_timeout parameter usage
8082
1.7. unused_timeout parameter usage
8183
1.8. pending_timeout parameter usage
82-
1.9. aka_www_authorize usage
83-
1.10. aka_proxy_authorize usage
84-
1.11. aka_www_challenge usage
85-
1.12. aka_proxy_challenge usage
86-
1.13. aka_av_add usage
87-
1.14. aka_av_drop usage
88-
1.15. aka_av_drop_all usage
89-
1.16. aka_av_fail usage
90-
1.17. aka_av_add usage
91-
1.18. aka_av_drop usage
92-
1.19. aka_av_drop_all usage
93-
1.20. aka_av_drop usage
84+
1.9. cachedb_url parameter usage
85+
1.10. aka_www_authorize usage
86+
1.11. aka_proxy_authorize usage
87+
1.12. aka_www_challenge usage
88+
1.13. aka_proxy_challenge usage
89+
1.14. aka_av_add usage
90+
1.15. aka_av_drop usage
91+
1.16. aka_av_drop_all usage
92+
1.17. aka_av_fail usage
93+
1.18. aka_av_add usage
94+
1.19. aka_av_drop usage
95+
1.20. aka_av_drop_all usage
96+
1.21. aka_av_drop usage
9497

9598
Chapter 1. Admin Guide
9699

@@ -148,23 +151,55 @@ Chapter 1. Admin Guide
148151
algorithms as well, but the response cannot be handled by this
149152
module, and an appropriate error will be returned.
150153

151-
1.4. Dependencies
154+
1.4. Clustering / Multi-Node Support
152155

153-
1.4.1. OpenSIPS Modules
156+
In distributed deployments where multiple OpenSIPS nodes handle
157+
SIP REGISTER requests, the AKA authentication flow requires that
158+
the authentication vector (AV) issued in the 401 challenge is
159+
available on the node that receives the subsequent authenticated
160+
REGISTER.
161+
162+
To support this scenario, the module can optionally use the
163+
OpenSIPS CacheDB infrastructure to synchronize authentication
164+
vectors across nodes. When the cachedb_url parameter is set:
165+
166+
* AVs are stored in the external cache when created
167+
* AVs are fetched from the cache when not found locally
168+
* AV state changes are synchronized to the cache
169+
* AVs are removed from the cache when they expire
170+
171+
Supported CacheDB backends include:
172+
* Redis (cachedb_redis module)
173+
* MongoDB (cachedb_mongodb module)
174+
* Cassandra (cachedb_cassandra module)
175+
* Any other CacheDB-compatible backend
176+
177+
Example configuration for a clustered setup:
178+
179+
loadmodule "cachedb_redis.so"
180+
loadmodule "auth_aka.so"
181+
modparam("cachedb_redis", "cachedb_url", "redis://redis-cluster:6379/")
182+
modparam("auth_aka", "cachedb_url", "redis://redis-cluster:6379/")
183+
184+
1.5. Dependencies
185+
186+
1.5.1. OpenSIPS Modules
154187

155188
The module depends on the following modules (in the other words
156189
the listed modules must be loaded before this module):
157190
* auth -- Authentication framework
158191
* AV manage module -- at least one module that fetches AVs
159192
and pushes them in the AV storage
193+
* cachedb_* module (optional) -- required only if cachedb_url
194+
is set for multi-node AV synchronization
160195

161-
1.4.2. External Libraries or Applications
196+
1.5.2. External Libraries or Applications
162197

163198
This module does not depend on any external library.
164199

165-
1.5. Exported Parameters
200+
1.6. Exported Parameters
166201

167-
1.5.1. default_av_mgm (string)
202+
1.6.1. default_av_mgm (string)
168203

169204
The default AV Manager used in case the functions do not
170205
provide them explicitly.
@@ -174,7 +209,7 @@ Chapter 1. Admin Guide
174209
modparam("auth_aka", "default_av_mgm", "diameter") # fetch AVs through t
175210
he Cx interface
176211

177-
1.5.2. default_qop (string)
212+
1.6.2. default_qop (string)
178213

179214
The default qop parameter used during challenge, if the
180215
functions do not provide them explicitly.
@@ -185,7 +220,7 @@ he Cx interface
185220

186221
modparam("auth_aka", "default_qop", "auth,auth-int")
187222

188-
1.5.3. default_algorithm (string)
223+
1.6.3. default_algorithm (string)
189224

190225
The default algorithm to be advertise during challenge, if the
191226
functions do not provide them explicitly. Note that at least
@@ -200,7 +235,7 @@ modparam("auth_aka", "default_qop", "auth,auth-int")
200235

201236
modparam("auth_aka", "default_algorithm", "AKAv2-MD5")
202237

203-
1.5.4. hash_size (integer)
238+
1.6.4. hash_size (integer)
204239

205240
The size of the hash that stores the AVs for each user. Must be
206241
a power of 2 number.
@@ -211,7 +246,7 @@ modparam("auth_aka", "default_algorithm", "AKAv2-MD5")
211246

212247
modparam("auth_aka", "hash_size", 1024)
213248

214-
1.5.5. sync_timeout (integer)
249+
1.6.5. sync_timeout (integer)
215250

216251
The amount of milliseconds a synchronous call should wait for
217252
getting an authentication vector.
@@ -225,7 +260,7 @@ modparam("auth_aka", "hash_size", 1024)
225260

226261
modparam("auth_aka", "sync_timeout", 200)
227262

228-
1.5.6. async_timeout (integer)
263+
1.6.6. async_timeout (integer)
229264

230265
The amount of milliseconds an asynchronous call should wait for
231266
getting an authentication vector.
@@ -242,7 +277,7 @@ modparam("auth_aka", "sync_timeout", 200)
242277

243278
modparam("auth_aka", "async_timeout", 2000)
244279

245-
1.5.7. unused_timeout (integer)
280+
1.6.7. unused_timeout (integer)
246281

247282
The amount of seconds an authentication vector that has not
248283
been used can stay in memory. Once this timeout is reached, the
@@ -256,7 +291,7 @@ modparam("auth_aka", "async_timeout", 2000)
256291

257292
modparam("auth_aka", "unused_timeout", 120)
258293

259-
1.5.8. unused_timeout (integer)
294+
1.6.8. pending_timeout (integer)
260295

261296
The amount of seconds an authentication vector that is being
262297
used in the authentication process shall stay in memory. Once
@@ -271,9 +306,43 @@ modparam("auth_aka", "unused_timeout", 120)
271306

272307
modparam("auth_aka", "pending_timeout", 10)
273308

274-
1.6. Exported Functions
309+
1.6.9. cachedb_url (string)
310+
311+
If set, this parameter enables the synchronization of
312+
authentication vectors across multiple OpenSIPS nodes through
313+
the CacheDB interface. This is essential for distributed/clustered
314+
deployments where one node may issue the 401 challenge and another
315+
node may receive the authenticated REGISTER request.
316+
317+
When enabled, authentication vectors are stored in the configured
318+
CacheDB backend (e.g., Redis, MongoDB, Cassandra) with a TTL based
319+
on the pending_timeout parameter plus a small margin.
320+
321+
The flow for multi-node authentication is:
322+
1. Node A receives initial REGISTER without credentials
323+
2. Node A fetches AV, stores it in CacheDB, sends 401
324+
3. Node B receives REGISTER with credentials
325+
4. Node B looks up AV locally, on miss fetches from CacheDB
326+
5. Node B validates credentials using the cached AV
327+
328+
If not set (default), authentication vectors are only stored
329+
locally and multi-node authentication will not work.
330+
331+
Example 1.9. cachedb_url parameter usage
332+
333+
# Using Redis for AV synchronization
334+
loadmodule "cachedb_redis.so"
335+
modparam("cachedb_redis", "cachedb_url", "redis://localhost:6379/")
336+
modparam("auth_aka", "cachedb_url", "redis://localhost:6379/")
337+
338+
# Using MongoDB for AV synchronization
339+
loadmodule "cachedb_mongodb.so"
340+
modparam("cachedb_mongodb", "cachedb_url", "mongodb://localhost:27017/opensips")
341+
modparam("auth_aka", "cachedb_url", "mongodb://localhost:27017/opensips")
342+
343+
1.7. Exported Functions
275344

276-
1.6.1. aka_www_authorize([realm]])
345+
1.7.1. aka_www_authorize([realm]])
277346

278347
The function verifies credentials according to RFC3310, by
279348
using an authentication vector priorly allocated by an
@@ -321,7 +390,7 @@ if (!aka_www_authorize("diameter", "siphub.com"))
321390
...
322391

323392

324-
1.6.2. aka_proxy_authorize([realm]])
393+
1.7.2. aka_proxy_authorize([realm]])
325394

326395
The function behaves the same as aka_www_authorize(), but it
327396
authenticates the user from a proxy perspective. It receives
@@ -338,7 +407,7 @@ if (!aka_proxy_authorize("siphub.com"))
338407
...
339408

340409

341-
1.6.3. aka_www_challenge([av_mgm[, realm[ ,qop[, alg]]]])
410+
1.7.3. aka_www_challenge([av_mgm[, realm[ ,qop[, alg]]]])
342411

343412
The function challenges a user agent. It fetches an
344413
authentication vector for each algorigthm used through the
@@ -408,7 +477,7 @@ if (!aka_www_authorize("siphub.com")) {
408477
}
409478
...
410479

411-
1.6.4. aka_proxy_challenge([realm]])
480+
1.7.4. aka_proxy_challenge([realm]])
412481

413482
The function behaves the same as aka_www_challenge(), but it
414483
challenges the user from a proxy perspective. It receives the
@@ -429,7 +498,7 @@ if (!aka_proxy_authorize("siphub.com"))
429498
...
430499

431500

432-
1.6.5. aka_av_add(public_identity, private_identity, authenticate,
501+
1.7.5. aka_av_add(public_identity, private_identity, authenticate,
433502
authorize, confidentiality_key, integrity_key[, algorithms])
434503

435504
Adds an authentication vector for the user identitied by
@@ -467,7 +536,7 @@ uthorize */
467536
"6151667b9ef815c1dcb87473685f062a" /* ik */);
468537
...
469538

470-
1.6.6. aka_av_drop(public_identity, private_identity, authenticate)
539+
1.7.6. aka_av_drop(public_identity, private_identity, authenticate)
471540

472541
Drops the authentication vector corresponding to the
473542
authenticate/nonce value for an user identitied by
@@ -490,7 +559,7 @@ aka_av_drop("sip:test@siphub.com", "test@siphub.com",
490559
"KFQ/MpR3cE3V9PxucEQS5KED8uUNYIAALFyk59sIJI4=");
491560
...
492561

493-
1.6.7. aka_av_drop_all(public_identity, private_identity[, count])
562+
1.7.7. aka_av_drop_all(public_identity, private_identity[, count])
494563

495564
Drops all authentication vectors for an user identitied by
496565
public_identity and private_identity. This function is useful
@@ -512,7 +581,7 @@ aka_av_drop("sip:test@siphub.com", "test@siphub.com",
512581
aka_av_drop_all("sip:test@siphub.com", "test@siphub.com", $var(count));
513582
...
514583

515-
1.6.8. aka_av_fail(public_identity, private_identity[, count])
584+
1.7.8. aka_av_fail(public_identity, private_identity[, count])
516585

517586
Marks the engine that an authentication vector query for a user
518587
has failed, unlocking the processing of the message.
@@ -537,9 +606,9 @@ aka_av_drop_all("sip:test@siphub.com", "test@siphub.com", $var(count));
537606
aka_av_fail("sip:test@siphub.com", "test@siphub.com", 3);
538607
...
539608

540-
1.7. Exported MI Functions
609+
1.8. Exported MI Functions
541610

542-
1.7.1. aka_av_add
611+
1.8.1. aka_av_add
543612

544613
Adds an Authentication Vector through the MI interface.
545614

@@ -574,7 +643,7 @@ JI4=
574643
6151667b9ef815c1dcb87473685f062a
575644
...
576645

577-
1.7.2. aka_av_drop
646+
1.8.2. aka_av_drop
578647

579648
Invalidates an Authentication Vector of an user identified by
580649
its authenticate value.
@@ -597,7 +666,7 @@ $ opensips-cli -x mi aka_av_drop \
597666
JI4=
598667
...
599668

600-
1.7.3. aka_av_drop_all
669+
1.8.3. aka_av_drop_all
601670

602671
Invalidates all Authentication Vectors of an user through the
603672
MI interface.
@@ -616,7 +685,7 @@ $ opensips-cli -x mi aka_av_drop_all \
616685
test@siphub.com
617686
...
618687

619-
1.7.4. aka_av_fail
688+
1.8.4. aka_av_fail
620689

621690
Indicates the fact that the fetching of an authentication
622691
vector has failed, unlocking the processing of the message.

0 commit comments

Comments
 (0)