6 API Definitions

29.5113GPP5G SystemEquipment Identity Register ServicesRelease 18Stage 3TS

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

6.1 N5g-eir_EquipmentIdentityCheck Service API

6.1.1 API URI

URIs of this API shall have the following root:

{apiRoot}/{apiName}/{apiVersion}/

where "apiRoot" is defined in clause 4.4.1 of 3GPP TS 29.501 [5], the "apiName" shall be set to "n5g-eir-eic" and the "apiVersion" shall be set to "v1" for the current version of this specification.

6.1.2 Usage of HTTP

6.1.2.1 General

HTTP/2, as defined in IETF RFC 7540 [7], 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].

HTTP messages and bodies for the N5g-eir_EquipmentIdentityCheck Service shall comply with the OpenAPI [8] specification contained in Annex A.

6.1.2.2 HTTP standard headers

6.1.2.2.1 General

The usage of HTTP standard headers shall be supported as specified in clause 5.2.2 of 3GPP TS 29.500 [4].

6.1.2.2.2 Content type

The following content types shall be supported:

– JSON, as defined in IETF RFC 8259 [9]. The use of the JSON format shall be signalled by the content type "application/json". See also clause 5.4 of 3GPP TS 29.500 [4].

– The Problem Details JSON Object (IETF RFC 7807 [10]. The use of the Problem Details JSON object in a HTTP response body shall be signalled by the content type "application/problem+json".

6.1.2.3 HTTP custom headers

6.1.2.3.1 General

In this release of this specification, no custom headers specific to the N5g-eir_EquipmentIdentityCheck Service are defined. For 3GPP specific HTTP custom headers used across all service based interfaces, see clause 5.2.3 of 3GPP TS 29.500 [4].

6.1.3 Resources

6.1.3.1 Overview

Figure 6.1.3.1-1: Resource URI structure of the n5g-eir-eic API

Table 6.1.3.1-1 provides an overview of the resources and applicable HTTP methods.

Table 6.1.3.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method or custom operation	Description
equipmentStatus	/equipment-status	GET	Retrieve the equipment status of the PEI

6.1.3.2 Resource: equipmentStatus

6.1.3.2.1 Description

This resource represents the equipmentStatus for a PEI.

6.1.3.2.2 Resource Definition

Resource URI: {apiRoot}/n5g-eir-eic/v1/equipment-status

This resource shall support the resource URI variables defined in table 6.1.3.2.2-1.

Table 6.1.3.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.1.1

6.1.3.2.3 Resource Standard Methods

6.1.3.2.3.1 GET

This method shall support the URI query parameters specified in table 6.1.3.2.3.1-1.

Table 6.1.3.2.3.1-1: URI query parameters supported by the GET method on this resource

Name	Data type	P	Cardinality	Description
pei	Pei	M	1	The PEI of the UE shall be included for equipment identify checking
supi	Supi	O	0..1	The SUPI of the UE
gpsi	Gpsi	O	0..1	The GPSI of the UE
supported-features	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.1.6 is supported.

This method shall support the request data structures specified in table 6.1.3.2.3.1-2 and the response data structures and response codes specified in table 6.1.3.2.3.1-3.

Table 6.1.3.2.3.1-2: Data structures supported by the GET Request Body on this resource

Data type	P	Cardinality	Description
n/a

Table 6.1.3.2.3.1-3: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
EirResponseData	M	1	200 OK	Upon success, a response body containing the Equipment Status shall be returned
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same 5G-EIR or 5G-EIR (service) set. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same 5G-EIR or 5G-EIR (service) set. (NOTE 2)
ProblemDetails	O	0..1	404 Not Found	The equipment identify checking has failed. The "cause" attribute may be used to indicate one of the following application errors: – ERROR_EQUIPMENT_UNKNOWN See table 6.1.5.3-1 for the description of this error.
NOTE : The mandatory HTTP error status codes for the GET method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] other than those specified in the table above also apply, with a ProblemDetails data type when needed (see clause 5.2.7 of 3GPP TS 29.500 [4]). NOTE 2: RedirectResponses may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.1.3.2.3.1-4: Headers supported by the 307 Response Code on this resource

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same 5G-EIR or 5G-EIR (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.1.3.2.3.1-5: Headers supported by the 308 Response Code on this resource

Name

Data type

Cardinality

Description

Location

string

An alternative URI of the resource located on an alternative service instance within the same 5G-EIR or 5G-EIR (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.1.4 Data Model

6.1.4.1 General

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

Table 6.1.4.1-1 specifies the data types defined for the n5g-eir-eic service based interface protocol.

Table 6.1.4.1-1: n5g-eir-eic specific Data Types

Data type	Clause defined	Description
EirResponseData	6.1.4.2.2
EquipmentStatus	6.1.4.3.3	Equipment status of the PEI, this data type is string.

Table 6.1.6.1-2 specifies data types re-used by the N_<NF> 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 N_<NF> service based interface.

Table 6.1.4.1-2: 5g-eir-eic re-used Data Types

Data type	Reference	Comments
Pei	3GPP TS 29.571[6]	Data type representing the PEI of the UE.
Supi	3GPP TS 29.571 [6]	Data type representing the SUPI of the subscriber. pattern: See pattern of type Supi in 3GPP TS 29.571 [6]
ProblemDetails	3GPP TS 29.571 [6]	Common data type for error responses
Gpsi	3GPP TS 29.571 [6]	Data type representing the GPSI of the subscriber.
SupportedFeatures	3GPP TS 29.571 [6]	Supported Features
RedirectResponse	3GPP TS 29.571 [6]	Response body of the redirect response message.

6.1.4.2 Structured data types

6.1.4.2.1 Introduction

This clause defines the structures to be used in resource representations.

6.1.4.2.2 Type: EirResponseData

Table 6.1.4.2.2-1: Definition of type EirResponseData

Attribute name	Data type	P	Cardinality	Description
status	EquipmentStatus	M	1	Status of the UE

6.1.4.3 Simple data types and enumerations

6.1.4.3.1 Introduction

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

6.1.4.3.2 Simple data types

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

Table 6.1.4.3.2-1: Simple data types

Type Name	Type Definition	Description
	<one simple data type, e.g. boolean, integer, null, number, string>

6.1.4.3.3 Enumeration: EquipmentStatus

Table 6.1.4.3.3-1: Enumeration EquipStatus

Enumeration value	Description
"WHITELISTED"	Indicates the PEI is permitted whitelisted
"BLACKLISTED"	Indicates the PEI is prohibited listed
"GREYLISTED"	Indicates the PEI is tracking listed

6.1.5 Error Handling

6.1.5.1 General

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

The Cause codes mapping performed by AMF between the following HTTP responses returned by the EIR services to the AMF and the 5GMM related values is specified in clause 4.5.2 of 3GPP TS 29.524 [15].

6.1.5.2 Protocol Errors

Protocol Error Handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].

6.1.5.3 Application Errors

The common application errors defined in the Table 5.2.7.2-1 in 3GPP TS 29.500 [4] may also be used for the N5g-eir_EquipmentIdentityCheck service, and the following application errors listed in Table 6.1.5.3-1 are specific for the N5g-eir_EquipmentIdentityCheck service.

Table 6.1.5.3-1: Application errors

Application Error	HTTP status code	Description
ERROR_EQUIPMENT_UNKNOWN	404 Not Found	Indicate the mobile equipment is not known in the EIR.

6.1.6 Feature Negotiation

The optional features in table 6.1.6-1 are defined for the N5g-eir_EquipmentIdentityCheck API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].

Table 6.1.6-1: Supported Features

Feature number

Feature Name

M/O

Description

ES3XX

Extended Support of HTTP 307/308 redirection

An NF Service Consumer (e.g. AMF) that supports this feature shall support handling of HTTP 307/308 redirection for any service operation of the EquipmentIdentityCheck service. An NF Service Consumer that does not support this feature does only support HTTP redirection as specified for 3GPP Release 15.

6.1.7 Security

6.1.7.1 General

The security mechanisms for service based interfaces are specified in clause 13 of 3GPP TS 33.501 [11] and in clause 6.7.3 of 3GPP TS 29.500 [4]. The access to the N5g-eir_EquipmentIdentityCheck API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [12]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [13]) plays the role of the authorization server.

The N5g-eir_EquipmentIdentityCheck API defines scopes for OAuth2 authorization as specified in 3GPP TS 33.501 [11]; it defines a single scope consisting on the name of the service (i.e., "n5g-eir-eic"), and it does not define any additional scopes at resource or operation level.

Security Protection Edge Proxy (SEPP), as specified in 3GPP TS 33.501 [11], shall be used between service based interfaces across PLMNs. The NFs in a PLMN shall use the SEPP as a HTTP/2 proxy for the HTTP/2 messages that carry ":authority" pseudo header with a uri-host formatted as specified in clause 6.1.4.3 of 3GPP TS 29.500 [4]

6.1.7.2 Transport Layer Security Protection of Messages

As specified in clause 13.1 of 3GPP TS 33.501 [11], TLS shall be used for the security protection of messages at the transport layer for the N5g-eir service based interface if network security is not provided by other means.

The protocol stack for the N5g-eir service based interface is shown on Figure 6.1.7.2-1.

Figure 6.1.7.2-1: SBI Protocol Stack

The N5g-eir service based interface uses HTTP/2 protocol (see clause 5.2) with JSON (see clause 5.4) as the application layer serialization protocol. For the security protection at the transport layer, 5G-EIR NF shall support TLS and TLS shall be used within a PLMN if network security is not provided by other means, as specified in 3GPP TS 33.501 [11].

6.1.7.3 Authorization of 5G-EIR NF Service Access

As specified in clause 13.4.1 of 3GPP TS 33.501 [11] OAuth 2.0 (see IETF RFC 6749 [12]) may be used for authorization of N5g-eir_EquipmentIdentityCheck service access. The 5G-EIR NF and the NRF (as defined in 3GPP TS 29.510 [13]) shall support the OAuth 2.0 authorization framework with "Client Credentials" grant type as specified in clause 4.4 of IETF RFC 6749 [12]. The NRF shall act as the Authorization Server providing the access tokens to the NF service consumers to access the service provided by the 5G-EIR. If the 5G-EIR NF receives an OAuth 2.0 authorization token in the "Authorization" HTTP request header field, the N5g-eir_EquipmentIdentityCheck service shall validate the access token, its expiry and its access scope before allowing access to the requested resource, as specified in clause 7 of IETF RFC 6749 [12].

6.1.8 HTTP redirection

An HTTP request may be redirected to a different 5G-EIR service instance, within the same 5G-EIR or a different 5G-EIR of an 5G-EIR set, e.g. when an 5G-EIR service instance is part of an 5G-EIR (service) set or when using indirect communications (see 3GPP TS 29.500 [4]). See also the ES3XX feature in clause 6.1.6.

An SCP that reselects a different 5G-EIR producer instance will return the NF Instance ID of the new 5G-EIR producer instance in the 3gpp-Sbi-Producer-Id header, as specified in clause 6.10.3.4 of 3GPP TS 29.500 [4].

If an 5G-EIR within an 5G-EIR set redirects a service request to a different 5G-EIR of the set using an 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new 5G-EIR towards which the service request is redirected shall be indicated in the 3gpp-Sbi-Target-Nf-Id header of the 307 Temporary Redirect or 308 Permanent Redirect response as specified in clause 6.10.9.1 of 3GPP TS 29.500 [4].

Annex A (normative):
OpenAPI specification