AKA Authentication Vector Diameter Module

This module is an extension to the AKA_AUTH module providing a Diameter AKA AV Manager that implements the Multimedia-Auth-Request and Multimedia-Auth-Answer Diameter commands defined in the Cx interface of the ETSI TS 129 229 specifications in order to fetch a set of authentication vectors and feed them in the AKA authentication process.

When the AKA_AUTH module needs a new authentication vector to do an aka_challenge(), it may require this module to fetch a set of authentication vectors for the purpose. The module packs the query in a MAR (Multimedia-Auth-Request) command and sends it to an HSS Diameter server. When an MAA (Multimedia-Auth-Answer) command is received in response, the corresponding authentication vectors are gathered and fed back to the AUTH_AKA engine.

It uses the AAA_Diameter module to perform the Diameter requests. It may run in both a synchronous and asynchronous mode, depending on how the AUTH_AKA module performs the query.

1.2. Setup

The module requires an aaa_diameter connection to an HSS Diameter server that implements the Cx interfaces and is able to provide authentication vectors through the Multimedia-Auth-Request and Multimedia-Auth-Answer commands.

The format of the command, along with the required fields can be found in the example/aka_av_diameter.dictionary file located in the module's source directory, as well as in the Diameter Commands Example section.

Note: the module internals uses the AVPs names found in the provided dictionary - changing the file may break the behavior of the module.

1.3. Dependencies

1.3.1. OpenSIPS Modules

The module depends on the following modules (in the other words the listed modules must be loaded before this module):

auth_aka -- AKA Authentication module that triggers the AKA authentication process
aaa_diameter -- AAA Diameter module that implements the Diameter communication to the HSS Server.

1.3.2. External Libraries or Applications

This module does not depend on any external library.

1.4. Exported Parameters

1.4.1. `aaa_url` (string)

This is the url representing the connection to the AAA server.

Note: Currently the module only supports connections to a Diameter server. The path to the AVPs configuration file is also required, otherwise the module will not start, or not work properly.

Example 1.1. aaa_url parameter usage

modparam("auth_aaa", "aaa_url", "diameter:freeDiameter.conf;extra-avps-file:/etc/freeDiameter/aka_av_diameter.dictionary")

1.4.2. `realm` (string)

The Realm used in the Origin Diameter commands.

Default value is “diameter.test”.

Example 1.2. realm parameter usage

		
modparam("aka_av_diameter", "realm", "scscf.ims.mnc001.mcc001.3gppnetwork.org")

1.5. Diameter Commands File

File that should be provided to the aaa_diameter connection.

Example 1.3. Diameter Commands File Example


VENDOR 10415 TGPP

ATTRIBUTE Public-Identity                     601 string     10415
ATTRIBUTE Server-Name                         602 string     10415
ATTRIBUTE 3GPP-SIP-Number-Auth-Items          607 unsigned32 10415
ATTRIBUTE 3GPP-SIP-Authentication-Scheme      608 utf8string 10415
ATTRIBUTE 3GPP-SIP-Authenticate               609 hexstring  10415
ATTRIBUTE 3GPP-SIP-Authorization              610 hexstring  10415
ATTRIBUTE 3GPP-SIP-Authentication-Context     611 string     10415
ATTRIBUTE 3GPP-SIP-Item-Number                613 unsigned32 10415
ATTRIBUTE Confidentiality-Key                 625 hexstring  10415
ATTRIBUTE Integrity-Key                       626 hexstring  10415


ATTRIBUTE 3GPP-SIP-Auth-Data-Item             612 grouped    10415
{
	3GPP-SIP-Item-Number | OPTIONAL | 1
	3GPP-SIP-Authentication-Scheme | OPTIONAL | 1
	3GPP-SIP-Authenticate | OPTIONAL | 1
	3GPP-SIP-Authorization | OPTIONAL | 1
	3GPP-SIP-Authentication-Context | OPTIONAL | 1
	Confidentiality-Key | OPTIONAL | 1
	Integrity-Key | OPTIONAL | 1
}

APPLICATION-AUTH 16777216/10415 3GPP Cx

REQUEST 303 Multimedia-Auth Request
{
	Session-Id | REQUIRED | 1
	Origin-Host | REQUIRED | 1
	Origin-Realm | REQUIRED | 1
	Destination-Realm | REQUIRED | 1
	Vendor-Specific-Application-Id | REQUIRED | 1
	Auth-Session-State | REQUIRED | 1
	User-Name | REQUIRED | 1
	Public-Identity | REQUIRED | 1
	3GPP-SIP-Number-Auth-Items | REQUIRED | 1
	3GPP-SIP-Auth-Data-Item | REQUIRED | 1
	Server-Name | REQUIRED | 1
}

ANSWER 303 Multimedia-Auth Answer
{
	Session-Id | REQUIRED | 1
	Origin-Host | REQUIRED | 1
	Origin-Realm | REQUIRED | 1
	Destination-Host | OPTIONAL | 1
	Destination-Realm | OPTIONAL | 1
	Vendor-Specific-Application-Id | REQUIRED | 1
	Auth-Session-State | REQUIRED | 1
	User-Name | REQUIRED | 1
	Public-Identity | REQUIRED | 1
	3GPP-SIP-Number-Auth-Items | REQUIRED | 1
	3GPP-SIP-Auth-Data-Item | REQUIRED | 1
	Result-Code | REQUIRED | 1
}

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

	Name	DevScore	Commits	Lines ++	Lines --
1.	Razvan Crainea (@razvancrainea)	13	4	941	4

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors⁽¹⁾ to this module

	Name	Commit Activity
1.	Razvan Crainea (@razvancrainea)	Mar 2024 - Mar 2024

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Razvan Crainea (@razvancrainea).