5.14 AKMA API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

5.14.1 Introduction

All resource URIs of this API should have the following root:

{apiRoot}/3gpp-akma/v1

"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-akma" and "apiVersion" shall be set to "v1" for the current version defined in the present document. All resource URIs in the clauses below are defined relative to the above root URI.

5.14.2 Resources

There are no resources defined for this API in this release of the specification.

5.14.3 Custom Operations without associated resources

5.14.3.1 Overview

The structure of the custom operation URIs of the AKMA API is shown in Figure 5.14.3.1-1.

Figure 5.14.3.1-1: Custom operation URI structure of the AKMA API

Table 5.14.3.1-1 provides an overview of the custom operations and applicable HTTP methods.

Table 5.14.3.1-1: Custom operations without associated resources

Operation name	Custom operation URI	Mapped HTTP method	Description
Retrieve	/retrieve	POST	Request to retrieve AKMA Application Key information

5.14.3.2 Operation: Retrieve

5.14.3.2.1 Description

The custom operation allows a service consumer to retrieve AKMA application key information via the NEF.

5.14.3.2.2 Operation Definition

This operation shall support the request and response data structures and response codes specified in tables 5.14.3.2.2-1 and 5.14.3.2.2-2.

Table 5.14.3.2.2-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
AkmaAfKeyRequest	M	1	Parameters to request to retrieve AKMA Application Key information.

Table 5.14.3.2.2-2: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AkmaAfKeyData	M	1	200 OK	The requested AKMA Application Key information was returned successfully.
n/a			204 No Content	If the requested data does not exist, the NEF shall respond with "204 No Content".
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
n/a			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]
ProblemDetails	O	0..1	403 Forbidden	(NOTE 2)
NOTE 1: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. NOTE 2: Failure cases are described in subclause 5.14.7.

Table 5.14.3.2.2-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.14.3.2.2-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.14.4 Notifications

Notifications are not applicable to this API.

5.14.5 Data Model

5.14.5.1 General

This clause specifies the application data model supported by the AKMA API.

5.14.5.2 Reused data types

The data types reused by the AKMA API from other specifications are listed in table 514.5.2-1.

Table 5.14.5.2-1: Re-used Data Types

Data type	Reference	Comments
DateTime	3GPP TS 29.122 [4]
Gpsi	3GPP TS 29.571 [8]
Supi	3GPP TS 29.571 [8]
SupportedFeatures	3GPP TS 29.571 [8]	Used to negotiate the applicability of the optional features.

5.14.5.3 Structured data types

5.14.5.3.1 Introduction

This clause defines the structured data types to be used in resource representations.

5.14.5.3.2 Type: AkmaAfKeyRequest

Table 5.14.5.3.2-1: Definition of type AkmaAfKeyRequest

Attribute name	Data type	P	Cardinality	Description	Applicability (NOTE)
afId	AfId	M	1	Identification of AF
aKId	AKId	M	1	A-KID
anonInd	boolean	O	0..1	Indicates whether an anonymous user access. Set to "true" if an anonymous user access is requested; otherwise set to "false". Default value is "false" if omitted.
suppFeat	SupportedFeatures	O	0..1	Indicates the list of Supported features used as described in clause 5.14.6.
NOTE: Properties marked with a feature as defined in clause 5.14.6 are applicable as described in clause 5.2.7 of 3GPP TS 29.122 [4]. If no feature is indicated, the related property applies for all the features.

5.14.5.3.3 Type: AkmaAfKeyData

Table 5.14.5.3.3-1: Definition of type AkmaAfKeyData

Attribute name	Data type	P	Cardinality	Description	Applicability (NOTE)
kaf	string	M	1	K_AF
expiry	DateTime	M	1	Expiration time of K_AF.
gpsi	Gpsi	O	0..1	Indicates an external ID of the UE. (NOTE 2, NOTE x)
supi	Supi	C	0..1	Indicates the SUPI of the UE. (NOTE 2)
suppFeat	SupportedFeatures	O	0..1	Indicates the features supported by both the AF and the NEF.
NOTE 1: Properties marked with a feature as defined in clause 5.14.6 are applicable as described in clause 5.2.7 of 3GPP TS 29.122 [4]. If no feature is indicated, the related property applies for all the features. NOTE 2: When the "AkmaAfKeyData" data structure is used in the current release of this specification, the "gpsi" attribute may be included and the "supi" attribute is not applicable. NOTE 3 When the "anonInd" attribute contained in AkmaAfKeyRequest data type is set to "true" in the incoming request, the "gpsi" attribute shall not be included.

5.14.5.4 Simple data types and enumerations

5.14.5.4.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

5.14.5.4.2 Simple data types

The simple data types defined in table 5.14.5.4.2-1 shall be supported.

Table 5.14.5.4.2-1: Simple data types

Type Name

Type Definition

Description

Applicability

AfId

string

Identification of AF which is formatted as the following string:

"<FQDN>.<Ua* security protocol id>", wherein, <FQDN> is the FQDN of the AF and <Ua* security protocol id> is a string of 5 octet and the identification of the Ua* security protocol is specified as Ua security protocol identifier in Annex H of 3GPP TS 33.220 [39] that the AF will use with the UE.

Example:

1. FQDN: www.app1.com, Ua* security protocol id: 0100BC0001, then AfId: www.app1.com.0100BC0001

AKId

string

AKMA Key Identifier shall be in NAI format as specified in clause 2.2 of IETF RFC 7542 [40], which is formatted as the following string:

"<username>@<realm>", wherein, <username> shall include Routing Indicatorand the A-TID in the format "rid<value>.atid<value>", where "rid" and "atid" are labels indicating Routing Indicator and A-TID and <realm> shall include Home Network Id.

Example:

1. If Routing Indicator: 012, A-TID: 019345346 and Home Network Id: 5gc.mnc012.mcc345.3gppnetwork.org, then AKId: rid012.akid019345346@5gc.mnc012.mcc345.3gppnetwork.org

Routing Indicator, Home Network Id are specified in 3GPP TS 23.003 [55].

A-TID is specified in 3GPP TS 33.535 [38].

5.14.6 Used Features

The table below defines the features applicable to the AKMA API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].

Table 5.14.6-1: Features used by AKMA API

Feature number	Feature Name	Description

5.14.7 Error handling

5.14.7.1 General

HTTP error handling shall be supported as specified in clause 5.2.6 of 3GPP TS 29.122 [4].

In addition, the requirements in the following clauses shall apply.

5.14.7.2 Protocol Errors

In this Release of the specification, there are no additional protocol errors applicable for the AKMA API.

5.14.7.3 Application Errors

The application errors defined for the AKMA API are listed in table 5.14.7.3-1.

Table 5.14.7.3-1: Application errors

Application Error	HTTP status code	Description
K_AKMA_NOT_PRESENT	403 Forbidden	Indicates that the K_AKMA identified by the A-KID provided in the AKMA Application Key retrieval request body is not present at the AAnF.