5 API Definitions
29.5353GPP5G SystemAKMA Anchor ServicesRelease 18Stage 3TS
5.1 Naanf_AKMA Service API
5.1.1 Introduction
The Naanf_AKMA service shall use the Naanf_AKMA API.
The API URI of the Naanf_AKMA API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].
– The <apiName> shall be "naanf-akma".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 5.1.3 and 5.1.4.
5.1.2 Usage of HTTP
5.1.2.1 General
HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].
HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].
The OpenAPI [6] specification of HTTP messages and content bodies for the Naanf_AKMA API is contained in Annex A.
5.1.2.2 HTTP standard headers
5.1.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
5.1.2.2.2 Content type
JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].
5.1.2.3 HTTP custom headers
The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4] may be supported..
In this release of the specification, no specific custom headers are defined for the Naanf_AKMA Service API.
5.1.3 Resources
There are no resources defined for this API in this release of the specification.
5.1.4 Custom Operations without associated resources
5.1.4.1 Overview
The structure of the custom operation URIs of the Naanf_AKMA API is shown in figure 5.1.4.1-1.
Figure 5.1.4.1-1: Custom operation URI structure of the Naanf_AKMA API
Table 5.1.4.1-1 provides an overview of the custom operations and applicable HTTP methods defined for the Naanf_AKMA API.
Table 5.1.4.1-1: Custom operations without associated resources
|
Operation |
Custom operation URI |
Mapped HTTP method |
Description |
|
register-anchorkey |
/register-anchorkey |
POST |
Request to store AKMA related key material in the AAnF. |
|
retrieve-applicationkey |
/retrieve-applicationkey |
POST |
Request to retrieve AKMA Application Key information. |
|
remove-context |
/remove-context |
POST |
Request to remove AKMA context in the AAnF. |
5.1.4.2 Operation: Register
5.1.4.2.1 Description
The custom operation allows a NF service consumer to store AKMA related key material in the AAnF.
5.1.4.2.2 Operation Definition
This operation shall support the response data structures and response codes specified in tables 5.1.4.2.2-1 and 5.1.4.2.2-2.
Table 5.1.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AkmaKeyInfo |
M |
1 |
AKMA related key material which is requested to be stored in the AAnF |
Table 5.1.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AkmaKeyInfo |
M |
1 |
200 OK |
The AKMA related key material was stored successfully. |
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during registration. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during registration. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
NOTE: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.1.4.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
Table 5.1.4.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
5.1.4.3 Operation: Retrieve
5.1.4.3.1 Description
The custom operation allows a NF service consumer to retrieve AKMA Application Key information for the UE.
5.1.4.3.2 Operation Definition
This operation shall support the response data structures and response codes specified in tables 5.1.4.3.2-1 and 5.1.4.3.2-2.
Table 5.1.4.3.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.1.4.3.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. (NOTE 2) |
|
n/a |
204 No Content |
If the requested data does not exist, the AAnF shall respond with "204 No Content". |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
ProblemDetails |
O |
0..1 |
403 Forbidden |
(NOTE 3) |
|
NOTE 1: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: For the "AkmaAfKeyData" data structure used in the current release of this specification, the “gpsi” attribute is not applicable and the "supi" attribute shall be included, except in the case of the anonymous user access procedure using the Naanf_AKMA_ApplicationKey_AnonUser_Get service operation, as defined in clause 6.2.2 of 3GPP TS 33.535 [14]. NOTE 3: Failure cases are described in clause 5.1.7.3 |
||||
Table 5.1.4.3.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
Table 5.1.4.3.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
5.1.4.4 Operation: Remove
5.1.4.4.1 Description
The custom operation allows a NF service consumer to delete the AKMA context for the UE.
5.1.4.4.2 Operation Definition
This operation shall support the response data structures and response codes specified in tables 5.1.4.4.2-1 and 5.1.4.4.2-2.
Table 5.1.4.4.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
CtxRemove |
M |
1 |
Parameters to request to delete the AKMA context for the UE. |
Table 5.1.4.4.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Successful case: The AKMA context matching the "CtxRemove" in the request body was deleted, the AAnF shall respond with "204 No Content". |
||
|
RedirectResponse |
O |
0..1 |
307 Temporary Redirect |
Temporary redirection, during remove procedure. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
RedirectResponse |
O |
0..1 |
308 Permanent Redirect |
Permanent redirection, during remove procedure. The response shall include a Location header field containing an alternative URI of the resource located in an alternative AAnF (service) instance. |
|
ProblemDetails |
O |
0..1 |
404 Not Found |
(NOTE 2) |
|
NOTE 1: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: Failure cases are described in clause 5.1.7.3 |
||||
Table 5.1.4.4.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
String |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
Table 5.1.4.4.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 AAnF (service) instance. |
|
3gpp-Sbi-Target-Nf-Id |
string |
O |
0..1 |
Identifier of the target AAnF (service) instance towards which the request is redirected. |
5.1.5 Notifications
Notifications are not applicable to this API.
5.1.6 Data Model
5.1.6.1 General
This clause specifies the application data model supported by the Naanf_AKMA API.
Table 5.1.6.1-1 specifies the data types defined for the Naanf_AKMA service based interface protocol.
Table 5.1.6.1-1: Naanf_AKMA specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
AkmaKeyInfo |
5.1.6.2.2 |
AKMA related key material. |
|
|
CtxRemove |
5.1.6.2.3 |
Indicate the AKMA context to be remove. |
Table 5.1.6.1-2 specifies data types re-used by the Naanf_AKMA service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Naanf_AKMA service based interface.
Table 5.1.6.1-2: Naanf_AKMA re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
AKId |
3GPP TS 29.522 [16] |
||
|
AkmaAfKeyData |
3GPP TS 29.522 [16] |
Parameters to present AKMA Application Key information. |
|
|
AkmaAfKeyRequest |
3GPP TS 29.522 [16] |
Parameters to request to retrieve AKMA Application Key information. |
|
|
RedirectResponse |
3GPP TS 29.571 [15] |
Contains redirection related information. |
|
|
Supi |
3GPP TS 29.571 [15] |
||
|
SupportedFeatures |
3GPP TS 29.571 [15] |
Used to negotiate the applicability of the optional features. |
5.1.6.2 Structured data types
5.1.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
5.1.6.2.2 Type: AkmaKeyInfo
Table 5.1.6.2.2-1: Definition of type AkmaKeyInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
supi |
Supi |
M |
1 |
SUPI of UE |
|
|
aKId |
AKId |
M |
1 |
A-KID |
|
|
kAkma |
string |
M |
1 |
KAKMA |
|
|
suppFeat |
SupportedFeatures |
O |
0..1 |
Indicates the list of Supported features used as described in clause 5.1.8. |
5.1.6.2.3 Type: CtxRemove
Table 5.1.6.2.3-1: Definition of type CtxRemove
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
supi |
Supi |
C |
0..1 |
SUPI of UE |
|
|
NOTE: In current release of specification, only "supi" can be used to indicate the AKMA context to be remove. The "supi" attribute shall be included. |
|||||
5.1.6.3 Simple data types and enumerations
5.1.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.1.6.3.2 Simple data types
None in this release of the specification.
5.1.6.4 Data types describing alternative data types or combinations of data types
None in this release of the specification.
5.1.6.5 Binary data
None in this release of the specification.
5.1.7 Error Handling
5.1.7.1 General
For the Naanf_AKMA API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].
In addition, the requirements in the following clauses are applicable for the Naanf_AKMA API.
5.1.7.2 Protocol Errors
No specific procedures for the Naanf_AKMA service are specified.
5.1.7.3 Application Errors
The application errors defined for the Naanf_AKMA service are listed in Table 5.1.7.3-1.
Table 5.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
K_AKMA_NOT_PRESENT |
403 Forbidden |
Indicates that the KAKMA identified by the A-KID provided in the AKMA Application Key retrieval request body is not present at the AAnF. |
|
AKMA_CONTEXT_NOT_FOUND |
404 Not Found |
Indicates that the AKMA context to be deleted indicated by the "CtxRemove" Data type in the request body is not found. |
5.1.8 Feature negotiation
The optional features in table 5.1.8-1 are defined for the Naanf_AKMA API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 5.1.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
5.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Naanf_AKMA API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.
If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Naanf_AKMA API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Naanf_AKMA service.
The Naanf_AKMA API defines a single scope "naanf-akma" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification