6 API Definitions
29.5443GPP5G SystemRelease 18Secured Packet Application Function (SP-AF) servicesStage 3TS
6.1 Nspaf_SecuredPacket Service API
6.1.1 Introduction
The Nspaf_SecuredPacket service shall use the Nspaf_SecuredPacket API.
The request URI used in HTTP request from the NF service consumer towards the NF service producer shall have the 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 "nspaf-secured-packet".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 6.1.3.
6.1.2 Usage of HTTP
6.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 Nspaf_SecuredPacket API is contained in Annex A.
6.1.2.2 HTTP standard headers
6.1.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
6.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].
6.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 applicable.
6.1.3 Resources
6.1.3.1 Overview
Figure 6.1.3.1-1: Resource URI structure of the nspaf-secured-packet 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 |
|
SecuredPacket (Custom operation) |
/{supi}/provide-secured-packet |
Provide-secured-packet (POST) |
The SP-AF generates a secured packet containing the presented UICC configuration parameter |
6.1.3.2 Resource: SecuredPacket
6.1.3.2.1 Description
This resource represents the information that is needed to construct secured packets for the SUPI.
6.1.3.2.2 Resource Definition
Resource URI: {apiRoot}/nspaf-secured-packet/v1/{supi}/provide-secured-packet
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 |
Definition |
|
apiRoot |
See clause 6.1.1 |
|
supi |
Represents the Subscription Permanent Identifier (see 3GPP TS 23.501 [2] clause 5.9.2) |
6.1.3.2.3 Resource Standard Methods
No Standard Methods are supported for this resource.
6.1.3.2.4 Resource Custom Operations
6.1.3.2.4.1 Overview
Table 6.1.3.2.4.1-1: Custom operations
|
Custom operaration URI |
Mapped HTTP method |
Description |
|
/provide-secured-packet |
POST |
The SP-AF generates a secured packet for the SUPI that contains the presented UICC configuration parameter. |
6.1.3.2.4.2 Operation: provide-secured-packet
6.1.3.2.4.2.1 Description
This custom operation is used by the NF service consumer (e.g. UDM) to request a secured packet for the SUPI containing the presented UICC configuration parameter. The returned secured packet shall be constructed as an SMS-Deliver as specified in 3GPP TS 23.040 [18] and protected as specified in 3GPP TS 31.115 [16].
6.1.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.1.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.1.3.2.4.2.2-2.
Table 6.1.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
UiccConfigurationParameter |
M |
1 |
Contains the parameter that is to be updated in the UICC |
Table 6.1.3.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
SecuredPacket |
M |
1 |
200 OK |
Upon success, a response body containing the generated secured packet shall be returned. |
|
ProblemDetails |
O |
0..1 |
404 Not Found |
The "cause" attribute may be used to convey the following application error: – USER_NOT_FOUND |
|
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. |
||||
6.1.4 Custom Operations without associated resources
In this release of this specification, no custom operations without associated resources are defined for the Nspaf_SecuredPacket Service.
6.1.5 Notifications
In this release of this specification, no notifications are defined for the Nspaf_SecuredPacket Service.
6.1.6 Data Model
6.1.6.1 General
This clause specifies the application data model supported by the API.
Table 6.1.6.1-1 specifies the data types defined for the Nspaf service based interface protocol.
Table 6.1.6.1-1: Nspaf specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
UiccConfigurationParameter |
6.1.6.2.2 |
UICC Configuration Parameters |
|
|
RoutingId |
6.1.6.3.2 |
Routing ID |
|
|
ExtendedSteeringContainer |
6.1.6.2.3 |
Extended Steering Container (including the contents of Steering Container and SOR-CMCI) |
Table 6.1.6.1-2 specifies data types re-used by the Nspaf 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 Nspaf service based interface.
Table 6.1.6.1-2: Nspaf re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
SecuredPacket |
3GPP TS 29.503 [14] |
Secured Packet |
|
|
ProblemDetails |
3GPP TS 29.571 [15] |
||
|
SteeringInfo |
3GPP TS 29.509 [17] |
Steering Information |
|
|
SorCmci |
3GPP TS 29.503 [14] |
Contains SOR-CMCI as defined in 3GPP TS 24.501 [19] |
6.1.6.2 Structured data types
6.1.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.1.6.2.2 Type: UiccConfigurationParameter
Table 6.1.6.2.2-1: Definition of type UiccConfigurationParameter
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
routingId |
RoutingId |
C |
0..1 |
The Routing Id that needs to be updated in the USIM. |
|
|
steeringContainer |
array(SteeringInfo) |
C |
1..N |
List of PLMN/AccessTechnologies combinations that need to be updated in the USIM. |
|
|
extendedSteeringContainer |
ExtendedSteeringContainer |
C |
0..1 |
Extended Steering Container that includes list of PLMN/AccessTechnologies combinations with the SOR-CMCI that need to be updated in the USIM |
|
|
Note: Exactly one attribute shall be present |
|||||
6.1.6.2.3 Type: ExtendedSteeringContainer
Table 6.1.6.2.3-1: Definition of type ExtendedSteeringContainer
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
steeringContainer |
array(SteeringInfo) |
C |
1..N |
List of PLMN/AccessTechnologies combinations that need to be updated in the USIM. |
|
|
sorCmci |
SorCmci |
C |
0..1 |
When present, provides the SOR-CMCI values as defined in 3GPP TS 24.501 [19] |
|
|
storeSorCmciInMe |
boolean |
C |
0..1 |
When present, indicates "Store the SOR-CMCI in the ME", i.e. whether to instruct UE to store SOR-CMCI in the ME as defined in 3GPP TS 23.122 [14] and 3GPP TS 24.501 [27]. – True: Indicates to store the SOR-CMCI in the ME – False or absent: Indicates storing the SOR-CMCI in the ME is not required |
|
|
NOTE: At least one attribute shall be present. If no additional attributes than steeringContainer is included, then use of steeringContainer can be considered instead of using ExtendedSteeringContainer. |
|||||
6.1.6.3 Simple data types and enumerations
6.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.
6.1.6.3.2 Simple data types
The simple data types defined in table 6.1.6.3.2-1 shall be supported.
Table 6.1.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
|
RoutingId |
string |
Pattern: "^[0-9]{1,4}$" |
6.1.7 Error Handling
6.1.7.1 General
For the Nspaf_SecuredPacket 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 Nspaf_SecuredPacket API.
6.1.7.2 Protocol Errors
No specific procedures for the Nspaf_SecuredPacket service are specified.
6.1.7.3 Application Errors
The application errors defined for the Nspaf_SecuredPacket service are listed in Table 6.1.7.3-1.
Table 6.1.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
USER_NOT_FOUND |
404 Not Found |
The user does not exist |
6.1.8 Feature negotiation
The optional features in table 6.1.8-1 are defined for the Nspaf_SecuredPacket API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 6.1.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
6.1.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nspaf_SecuredPacket 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 Nspaf_SecuredPacket 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 Nspaf_SecuredPacket service.
The Nspaf_SecuredPacket API defines a single scope "nspaf-secured-packet" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification