5 St protocol

29.1553GPPRelease 17Representational State Transfer (REST) over St reference pointTraffic steering controlTS

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

5.1 Introduction

The following layers of the protocol stack for the St reference point between PCRF and TSSF are described in subclauses:

– TCP as defined in IETF RFC 793 [3] provides the communication service at the transport layer.

– An optional communication security layer can be added between the transport and the application delivery layer (see clause 6).

– The application delivery layer provides the transport of the specific application communication data using HTTP/1.1 as defined in IETF RFC 7230 [22], IETF RFC 7231 [23], IETF RFC 7232 [24], IETF RFC 7233 [25], IETF RFC 7234 [26] and IETF RFC 7235 [27].

– The specific application communication layer constitutes the transport of the JSON content type.

Figure 5.1.1 illustrates the protocol stack of the RESTful St reference point.

Figure 5.1.1: Protocol stack of the RESTful St reference point

5.2 Transport layer

HTTP is layered over TCP, which provides a reliable transport.

For traffic steering policy provisioning and querying, the PCRF acts as an HTTP client and the TSSF acts as an HTTP server. As a result, the PCRF shall initiate a TCP connection with the TSSF.

If the notification feature is supported by TSSF and PCRF, then the TSSF and PCRF shall also respectively act as HTTP client and server. In this case, the TSSF shall initiate a TCP connection with the PCRF.

5.3 Application delivery layer

The application delivery layer shall use RESTful HTTP.

The application delivery layer provides the following services:

– session establishment including the creation of the session resource.

– session modification and termination procedures.

– session notification procedures.

In order to establish an St session, the PCRF shall send an HTTP POST message to the TSSF including all session information required. The PCRF shall assign a globally and eternally unique St Session ID and shall include it as part of the session resource representation within the body of the HTTP POST. The St Session ID is defined in subclause 5.3.4. If the session resource is successfully created at the TSSF, the TSSF shall provide the session resource URI within the Location header of the HTTP response.

In order to modify an St session, the PCRF shall send an HTTP PUT (full replacement of the St session resource) or an HTTP PATCH message, which includes the St session ID as a path element of the URI.

In order to query the state of an St session, the PCRF shall send an HTTP GET message including the St Session ID as a path element of the request URI.

In order to delete an St session, the PCRF shall send an HTTP DELETE message including the St session ID as a path element of the request URI.

In order to report traffic steering rule enforcement failures for an St session, if the notification feature is supported by both the PCRF and TSSF, the TSSF shall send an HTTP POST message including the St session ID as a path element of the notification URI.

Every HTTP message contains the specific communication information required for this case in its body.

5.3.1 Methods

Methods indicate to the server what action has to be performed. Every HTTP request message has a method. The following HTTP methods as defined in IETF RFC 7231 [23] and IETF RFC 5789 [12] can be used:

– POST:

– Used to create a resource state. The request URI defines the address responsible for the creation of the resource.

– Used to report traffic steering rule enforcement failures from the TSSF to the PCRF. The notification report is provided in the body of the message. The request URI defines the address of the impacted resource.

– PUT: Used to replace a resource state. The full state of the resource is provided in the body of the message. The request URI defines the resource which will be replaced.

– PATCH: The PATCH method applies partial modifications to a resource. The request URI defines the resource which will be modified.

– GET: Used to retrieve a resource state. The request URI defines the resource which is queried. The server returns the resource state representation within the body of the response.

– DELETE: Used to delete a resource state. The request URI defines the resource which will be deleted.

Every HTTP request results in a response message that comes back with a status code and further information in its body, if required. The PCRF waits for this response before initiating a further request for the same resource.

5.3.2 Resources and URI design

The St session is a RESTful resource that shall be identified by a URI.

The URI design shall be based on the structure defined in IETF RFC 3986 [13]:

scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty

The scheme may be HTTP or HTTPS for the REST St interface. Within a scheme the definition of names shall follow the rules of HTTP URIs. Host and port are the main parts of the authority. The path element identifies the resources.

For the REST St interface, the following required parts of the URI shall be used as follows:

– scheme: The application delivery layer protocol "http" or "https".

– authority: It includes the server address and optionally a port as follows: host [":" port]

– path-absolute: The path-absolute should have the following ABNF: "/" mainapp "/" mainresource ["/" resourcepath], where for this release, "mainapp" is "stapplication", "mainresource" is "sessions" and "resourcepath contains the path to identify a session resource, which in this release is the St Session ID as defined in subclause 5.3.4.

NOTE: A different path can be used when the Resource URI is preconfigured in the PCRF.

An example of the URI to identify the "sessions" main resource is: http://tssfserver.example.com/stapplication/sessions.

5.3.3 HTTP request/response formats

5.3.3.1 General

Session establishment, modification, termination and query procedures are performed through HTTP transactions consisting of a request initiated by the PCRF and its corresponding response provided by the TSSF.

Table 5.3.3.1-1 summarizes the content of the requests and responses. More detailed information is specified in the corresponding subclauses as indicated in the table.

Table 5.3.3.1-1: St requests/response summary table

Method	Resource URI’s path (NOTE 1)	Clause Defined	Request body	Response body
POST	/stapplication/sessions	5.3.3.2	Content-Type: application/json The PCRF shall include the state of the session resource using the schema defined in Annex B.1.	Successful response: The TSSF may include informational data in the body of the response as per Annex B.2 Error response: The TSSF should include error data in the body of the response as per Annex B.2
PUT	/stapplication/sessions/{stsessionid}	5.3.3.3	Content-Type: application/json The PCRF shall include the state of the session resource using the schema defined in Annex B.1.	Successful response: The TSSF may include informational data in the body of the response as per Annex B.2 Error response: The TSSF should include error data in the body of the response as per Annex B.2
PATCH	/stapplication/sessions/{stsessionid}	5.3.3.4	Content-Type: application/json-patch+json The PCRF shall include the partial modifications to the state of the session resource using the schema defined in Annex B.1.	Successful response: The TSSF may include informational data in the body of the response as per Annex B.2 Error response: The TSSF should include error data in the body of the response as per Annex B.2
DELETE	/stapplication/sessions/{stsessionid}	5.3.3.5	None	Successful response: The TSSF may include informational data in the body of the response as per Annex B.2 Error response: The TSSF should include error data in the body of the response as per Annex B.2
GET	/stapplication/sessions/{stsessionid}	5.3.3.6	None	Successful response: The TSSF shall include the representation of the corresponding session resource in the body of the response as per Annex B.2 Error response: The TSSF should include error data in the body of the response as per Annex B.2
POST	/{notificationbaseurl}/{stsessionid}	5.3.3.7	Content-Type: application/json The TSSF shall report traffic steering rule enforcement failures to the PCRF using the JSON format definition in Annex B.4	Successful response: The PCRF may include informational data in the body of the response as per Annex B.2 Error response: The PCRF should include error data in the body of the response as per Annex B.2
NOTE: A different path from /stapplication/sessions/ may be used when it is configured in the PCRF. In that case the "path" part set in the different methods should use the configured one.

5.3.3.2 POST /stapplication/sessions

The establishment of a session shall be performed by the PCRF by using the POST method as follows:

– the request URI formatted as defined in subclause 5.3.2 with the "path" part set to: /stapplication/sessions.

– the Content-Type header field set to "application/json"

– the body of the message encoded in JSON format as defined in Annex B.1, including the "session-id" field allocated by the PCRF.

The PCRF sets the URI based on the pre-configuration at the PCRF.

If the PCRF supports the Notification feature, it shall follow the procedures defined in subclause 5.3.6.1 to advertise support of the feature. In addition, the PCRF shall include the 3gpp-Notification-Base-URL header as defined in subclause 5.3.7.4.

Upon receipt of the HTTP POST, the TSSF shall respond to the PCRF indicating whether the creation of the resource was successful or not using one of the HTTP status codes as defined in subclause 5.3.5. If the resource creation is successful, the TSSF shall respond with an HTTP 201 (Created) status code, including a Location header field containing the URI for the created session resource based on the St Session ID as defined in subclause 5.3.4. If the creation of the session resource was not successful, the TSSF shall indicate the reason using an appropriate HTTP status code for the St interface as defined in subclause 5.3.5 and optionally additional information in the body of the response as defined in Annex B.2.

If both the PCRF and TSSF support the Notification feature, the TSSF shall remember the value of the 3gpp-Notification-Base-URL for the lifetime of the corresponding St session and shall initiate a TCP connection towards the PCRF (if it is not already established) based on the hostname and optional port elements of the 3gpp-Notification-Base-URL.

NOTE: Network deployment scenario with overlapping IP address assignment where the PCRF connects to multiple PCEFs connecting to the same PDN and where these multiple PCEFs connect to the same TSSF is not supported in this release.

Below is an example of an HTTP POST and a corresponding successful response:

POST /stapplication/sessions HTTP/1.1

Host: tssfserver.example.com

3gpp-Notification-Base-URL: http://pcrfserver.example.com:8080/stapplication/notification

3gpp-Optional-Features: Notification

Content-Type: application/json

Content-Length: …

{

"session-id": "pcrf.example.com;378388838383;123232",

"ue-ipv4": "10.0.0.2",

"called-station-id": "apncompany.com",

"tsrules": {

"ts-rule-3": {

"ts-rule-name": "ts-rule-3",

"tdf-application-identifier": "ftp-download",

"precedence": 1,

"ts-policy-identifier-dl": "firewall"

}

Here is an example of a successful response:

HTTP/1.1 201 Created

Location: http:// tssfserver.example.com/stapplication/sessions/pcrf.example.com;378388838383;123232

Date: Mon, 23 Apr 2012 17:10:00 GMT

Server: tssf.example.com

3gpp-Accepted-Features: Notification

Content-Type: application/json

{

"success-message": "Session was created successfully.",

}

5.3.3.3 PUT /stapplication/sessions/{stsessionid}

The full modification of a session resource may be performed by the PCRF using the PUT method. In this case, the PCRF shall send an HTTP PUT request as follows:

– the request URI formatted as defined in subclause 5.3.2 with the "path" part set to: /stapplication/sessions/{stsessionid}, where the stsessionid is the St Session ID as defined in subclause 5.3.4.

– the Content-Type header field set to "application/json"

– the body of the message encoded in JSON format as defined in Annex B.1 specifying the full representation of the session resource

Upon receipt of the HTTP PUT, the TSSF shall respond to the PCRF indicating whether the modification of the resource was successful or not using one of the HTTP status codes as defined in subclause 5.3.5. If the resource modification is successful, the TSSF shall respond with an HTTP 200 OK status code if it includes optional informational data in the body of the response as per Annex B.2 or HTTP 204 No Content status code otherwise. If the modification of the session resource was not successful, the TSSF shall indicate the reason using an appropriate HTTP status code for the St interface as defined in subclause 5.3.5 and optionally additional information in the body of the response as defined in Annex B.2.

Below is an example of an HTTP PUT:

PUT /stapplication/sessions/pcrf.example.com;378388838383;123232 HTTP/1.1

Host: tssfserver.example.com

Content-Type: application/json

Content-Length: …

{

"session-id": "pcrf.example.com;378388838383;123232",

"ue-ipv4": "10.0.0.2",

"tsrules": {

"ts-rule-1": {

"ts-rule-name": "ts-rule-1",

"tdf-application-identifier": "ftp-download",

"precedence": 1,

"ts-policy-identifier-dl": "firewall"

"ts-rule-2": {

"ts-rule-name": "ts-rule-2",

"tdf-application-identifier": "application-x",

"precedence": 2,

"ts-policy-identifier-dl": "firewall"

}

Here is an example of a successful response:

HTTP/1.1 200 OK

Date: Mon, 23 Apr 2012 17:11:00 GMT

Server: tssf.example.com

Content-Type: application/json

{

"success-message": "Session was updated successfully.",

}

5.3.3.4 PATCH /stapplication/sessions/{stsessionid}

The partial modification of a session resource may be performed by the PCRF using the PATCH method as defined in IETF RFC 5789 [12]. In this case, the PCRF shall send an HTTP PATCH request as follows:

– the Content-Type header field set to "application/json-patch+json"

– the body of the message shall be encoded using the JSON Patch format as defined in IETF RFC 6902 [14]. The following operations from [14] may be used:

– add: to create a new traffic steering rule.

– remove: to delete a traffic steering rule.

– replace: to replace an existing rule with a new definition.

Upon receipt of the HTTP PATCH, the TSSF shall respond to the PCRF indicating whether the modification of the resource was successful or not using one of the HTTP status codes as defined in subclause 5.3.5. If the resource modification is successful, the TSSF shall respond with an HTTP 200 OK status code if it includes optional informational data in the body of the response as per Annex B.2 or HTTP 204 No Content status code otherwise. If the modification of the session resource was not successful, the TSSF shall indicate the reason using an appropriate HTTP status code for the St interface as defined in subclause 5.3.5 and optionally additional information in the body of the response as defined in Annex B.2.

Below is an example of an HTTP PATCH that modifies a traffic steering rule and deletes another one:

PATCH /stapplication/sessions/pcrf.example.com;378388838383;123232 HTTP/1.1

Host: tssfserver.example.com

Content-Type: application/json-patch+json

Content-Length: …

[

{

"op": "replace",

"path": "/tsrules/ts-rule-1",

"value": {

"ts-rule-name": "ts-rule-1",

"tdf-application-identifier": "ftp-download",

"precedence": 1,

"ts-policy-identifier-dl": "firewall2"

}

{

"op": "remove",

"path": "/tsrules/ts-rule-2",

}

]

Here is an example of a successful response:HTTP/1.1 200 OK

Date: Mon, 23 Apr 2012 17:12:00 GMT

Server: tssf.example.com

Content-Type: application/json

{

"success-message": "Session was patched successfully.",

}

5.3.3.5 DELETE /stapplication/sessions/{stsessionid}

To delete an St session, the PCRF shall send an HTTP DELETE request to the TSSF as follows:

Upon receipt of the HTTP DELETE, the TSSF shall respond to the PCRF indicating whether the deletion of the resource was successful or not using one of the HTTP status codes as defined in subclause 5.3.5. If the resource deletion is successful, the TSSF shall respond with an HTTP 200 OK status code if it includes optional informational data in the body of the response as per Annex B.2 or HTTP 204 No Content status code otherwise. If the deletion of the session resource was not successful, the TSSF shall indicate the reason using an appropriate HTTP status code for the St interface as defined in subclause 5.3.5 and optionally additional information in the body of the response as defined in Annex B.2.

Below is an example of an HTTP DELETE:

DELETE /stapplication/sessions/pcrf.example.com;378388838383;123232 HTTP/1.1

Host: tssfserver.example.com

Here is an example of a successful response:

HTTP/1.1 204 No Content

Date: Mon, 23 Apr 2012 17:15:00 GMT

Server: tssf.example.com

5.3.3.6 GET /stapplication/sessions/{stsessionid}

To query the state of an St session resource, the PCRF shall send an HTTP GET request to the TSSF as follows:

Upon receipt of the HTTP GET, the TSSF shall respond to the PCRF indicating whether the querying of the resource was successful or not using one of the HTTP status codes as defined in subclause 5.3.3. If the resource exists, the TSSF shall respond with an HTTP 200 OK status code and include the session representation state within the body of the response as defined in Annex B.2. The TSSF shall also include the Content-Type header field set to "application/json".

The TSSF shall also include the set of features it supports in common with the PCRF within the "3gpp-Accepted-Features" HTTP header in the response to the HTTP GET.

Below is an example of an HTTP GET:

GET /stapplication/sessions/pcrf.example.com;378388838383;123232 HTTP/1.1

Host: tssfserver.example.com

Here is an example of a successful response :

HTTP/1.1 200 OK

Server: tssfserver.example.com

Content-Type: application/json

Content-Length: …

{

"session-id": "pcrf.example.com;378388838383;123232",

"ue-ipv4": "10.0.0.2",

"called-station-id": "apncompany.com",

"tsrules": {

"ts-rule-1": {

"ts-rule-name": "ts-rule-1",

"tdf-application-identifier": "ftp-download",

"precedence": 1,

"ts-policy-identifier-dl": "firewall"

"ts-rule-2": {

"ts-rule-name": "ts-rule-2",

"tdf-application-identifier": "application-x",

"precedence": 2,

"ts-policy-identifier-dl": "firewall"

}

5.3.3.7 POST /{notificationbaseurl}/{stsessionid}

If the notification feature is supported, the TSSF shall inform the PCRF of state changes related to a session resource or sub resources (e.g. traffic steering rules). The TSSF does so by sending an HTTP POST request as follows:

– the request URI formatted as defined in subclause 5.3.2 with the "path" part set to: /{notificationbaseurl}/ {stsessionid}, where the "stsessionid" is the St Session ID as defined in subclause 5.3.4, and the "notificationbaseurl" is set to the value of the 3gpp-Notification-Base-URL provided by the PCRF.

– the Content-Type header field set to "application/json"

– the body of the message encoded in JSON format as defined in Annex B.4 specifying the representation of the notification report.

Upon receipt of the notification HTTP POST, the PCRF shall respond to the TSSF with one of the HTTP status codes as defined in subclause 5.3.5. If the PCRF is able to successfully process the request, the PCRF shall answer with an HTTP 200 OK status code if it includes optional informational data in the body of the response as per Annex B.2 or HTTP 204 No Content status code otherwise. If the PCRF cannot successfully process the request, the PCRF shall indicate the reason using an appropriate HTTP status code for the St interface as defined in subclause 5.3.5 and optionally include additional information in the body of the response as defined in Annex B.2.

Below is an example of an HTTP POST used for notification of traffic steering rule enforcement failure.

POST /stapplication/notification/pcrf.example.com;378388838383;123232 HTTP/1.1

Host: pcrfserver.example.com

Content-Type: application/json

Content-Length: …

{

"notifications": [

{

"notification-message": "Traffic steering rules became inactive.",

"notification-type": "application",

"notification-tag": "TS_RULE_EVENT",

"notification-info": {

"ts-rule-reports": [

{

"resource-paths": [

"/tsrules/ts-rule-1",

"/predefined-tsrules/ts-rule-2",

"/predefined-group-of-tsrules/group-rules-1"

"rule-status": "INACTIVE",

"rule-failure-code": "RESOURCES_LIMITATION"

}

]

}

]

}

Here is an example of a successful response:

HTTP/1.1 200 OK

Date: Mon, 23 Apr 2012 17:11:00 GMT

Server: pcrfserver.example.com

Content-Type: application/json

{

"success-message": "Notification was processed successfully.",

}

5.3.4 St session ID

The PCRF shall allocate an St Session ID that is used to uniquely identify the St session resource between the PCRF and TSSF. The St Session ID is provided as part of the session resource representation within the body of the HTTP message and shall remain unmodified during the lifetime of the St session resource. If the session resource is successfully created at the TSSF, the TSSF shall include the St session ID in the path element of an HTTP request URI to address the corresponding session resource.

NOTE: The PCRF allocates the St Session ID as opposed to the TSSF to avoid creating duplicate sessions at the TSSF in case an HTTP POST message is received twice by the TSSF (e.g. due to a retry by the PCRF). The PCRF ensures that the St Session ID is globally unique as described in this subclause to avoid conflicts at the TSSF.

The Session ID shall be globally and eternally unique. The Session ID includes a mandatory portion and an implementation specific portion.

The mandatory portion shall start with the PCRF’s FQDN [8]. The remainder of the Session ID is delimited by a ‘;’ character and may be any sequence that the PCRF can guarantee to be eternally unique as follows:

The implementation specific sequence should follow the recommended implementation specific portion of the Session-Id AVP as defined in section 8.8 of IETF RFC 6733 [21].

Here is an example of the Session ID: pcrf123.acme.com;1876543210;523. Here is an example of a corresponding session URI: http://tssfserver.example.com/stapplication/sessions/pcrf123.acme.com;1876543210;523

Because the Session ID is included as a path element of the request URI, it shall follow the implementation-specific syntax standardized for path elements of URLs as defined in [6].

NOTE: Characters in the reserved set are protected from normalization and are therefore safe to be used by scheme-specific and producer-specific algorithms for delimiting data subcomponents within a URI [6].

5.3.5 HTTP status codes

A subset of the HTTP status codes as defined in IETF RFC 7231 [23] are applicable to the REST based St interface. Table 5.3.5-1 lists the applicable status codes for the St interface for the current release. Note that if the PCRF or TSSF receive a response with a status code not listed in the table below, they shall treat it based on the class of the status code as defined in IETF RFC 7231 [23].

Table 5.3.5-1: St HTTP status codes

Status Code	Description
200 OK	The HTTP request has succeeded. The information returned with the response is dependent on the method used in the request.
201 Created	The HTTP POST request has been fulfilled and resulted in a new resource being created at the TSSF.
204 No Content	The recipient has fulfilled the request but does not need to return an entity-body.
400 Bad Request	The request could not be processed due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
403 Forbidden	The recipient understood the request, but is refusing to fulfill it.
404 Not Found	The recipient has not found any resources matching the Request-URI.
405 Method Not Allowed	The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
408 Request Timeout	The recipient did not respond to the request within the time that the sender is prepared to wait. The sender may repeat the request without modifications at any later time.
412 Precondition Failed	The precondition given in one or more of the request-header fields evaluated to false when it was tested on the recipient.
413 Payload Too Large	The recipient is refusing to process a request because the request entity is larger than the recipient is willing or able to process.
414 URI Too Long	The recipient is refusing to service the request because the Request-URI is longer than the recipient is willing to interpret.
500 Internal Server Error	The recipient encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented	The recipient does not support the functionality required to fulfill the request.
503 Service Unavailable	The recipient is currently out of service.

5.3.6 Feature negotiation

5.3.6.1 General

The REST based St interface needs to provide a mechanism to advertise required and optional features supported by both the PCRF and TSSF for interoperability reasons as the functionality of the REST St based interface is augmented.

The PCRF shall include in the HTTP POST the set of supported features as follows:

– if a feature is required for the proper operation of the St session, it shall be included within the 3gpp-Required-Features header;

– if a feature is optional for the proper operation of the St session, it shall be included within the 3gpp-Optional-Features header.

The TSSF shall include, within the 3gpp-Accepted-Features header in the response to the HTTP POST, the set of features it supports in common with the PCRF.

If the TSSF does not support any of the required features advertised by the PCRF within the 3gpp-Required-Features header, the TSSF shall reject the HTTP POST with an HTTP 412 Precondition Failed status code and shall include the commonly supported features with the PCRF within the 3gpp-Accepted-Features.

If the TSSF requires certain features to be supported that aren’t advertised by the PCRF, the TSSF shall reject the HTTP POST with an HTTP 412 Precondition Failed status code and shall include the commonly supported features with the PCRF within the 3gpp-Accepted-Features and the required features in the 3gpp-required-features.

If the PCRF and TSSF successfully negotiate supported features, the list of commonly supported features shall be applicable for the lifetime of the St session. Features that are not advertised as supported shall not be used within the lifetime of the St session.

The table below defines the features applicable to the REST St interface.

Table 5.3.6.1-1: Features used in REST St Protocol

Feature

M/O

Description

Notification

This feature indicates the support of the HTTP notification procedure from the TSSF to the PCRF.

Feature: A short name that can be used to refer to the bit and to the feature, e.g. "Notification".

M/O: Defines if the implementation of the feature is mandatory ("M") or optional ("O") in this 3GPP Release.

Description: A clear textual description of the feature.

5.3.7 HTTP custom headers

This subclause defines any new HTTP custom headers introduced by this specification.

5.3.7.1 3gpp-Optional-Features

This header is used by the PCRF to advertise the optional features that are supported by the PCRF.

The encoding of the header follows the ABNF as defined in IETF RFC 7231 [23].

3gpp-Optional-Features = "3gpp-Optional-Features" ":" 1#token

An example is: 3gpp-Optional-Features: feature1, feature2

5.3.7.2 3gpp-Required-Features

This header is used by the PCRF to announce the mandatory features that must be supported in TSSF.

This header is also used by the TSSF to indicate the missing features that must be supported in PCRF.

The encoding of the header follows the ABNF as defined in IETF RFC 7231 [23].

3gpp-Required-Features = "3gpp-Required-Features" ":" 1#token

An example is: 3gpp-Required-Features: feature1, feature2

5.3.7.3 3gpp-Accepted-Features

The header is used by the TSSF to confirm the commonly supported set of features with the PCRF.

The encoding of the header follows the ABNF as defined in IETF RFC 7231 [23].

3gpp-Accepted-Features = "3gpp-Accepted-Features" ":" 1#token

An example is: 3gpp-Accepted-Features: feature1, feature2

5.3.7.4 3gpp-Notification-Base-URL

This header is used by the PCRF to provide the notification base URL.

The encoding of the header follows the ABNF as defined in IETF RFC 7231 [23].

3gpp-Notification-Base-URL = "3gpp-Notification-Base-URL " ":" 1#token

An example is: 3gpp-Notification-Base-URL: http://pcrfserver.example.com:8080/stapplication/notification

5.4 Specific application communication

5.4.1 General

Specific application communication represents the presentation of application data structures by transforming data into the form that the application accepts. It establishes the context between application-layer entities.

Note: This release only supports the content type JSON

5.4.2 Content type

The body of HTTP messages shall be in JSON format. The content of the JSON text is defined in subclause 5.4.3 and Annex B.

The MIME media type that shall be used within the Content-Type header field is "application/json" as defined in IETF RFC 7159 [10].

5.4.3 JSON session fields

5.4.3.1 General

Table 5.4.3.1.1 describes the JSON fields used within the body of the HTTP messages representing the session information. The table includes the information about the name of the field, the type of the fields and the applicability of the JSON field.

Table 5.4.3.1.1: St Specific JSON fields

				Applicability (NOTE 3)
Field Name	Subclause defined	JSON Value Type (NOTE 1)	JCR Type (NOTE 2)
called-station-id	5.4.3.20	string	string
session-id	5.4.3.2	string	string
ue-ipv4	5.4.3.3	string	ipv4
ue-ipv6-prefix	5.4.3.4	string	Ipv6
tsrules	5.4.3.5	object	object
ts-rule-name	5.4.3.6	string	string
Precedence	5.4.3.7	number	number: 0..4294967295
tdf-application-identifier	5.4.3.8	string	string
flow-information	5.4.3.9	array	array
flow-description	5.4.3.10	string	string
tos-traffic-class	5.4.3.11	string	/^[0-9A-Fa-f]{4}$/ (NOTE 4)
security-parameter-index	5.4.3.12	string	/^[0-9A-Fa-f]{8}$/ (NOTE 4)
flow-label	5.4.3.13	string	/^[0-9A-Fa-f]{6}$/ (NOTE 4)
flow-direction	5.4.3.14	string	"BIDIRECTIONAL" "UPLINK" "DOWNLINK" (NOTE 5)
ts-policy-identifier-dl	5.4.3.15	string	string
ts-policy-identifier-ul	5.4.3.16	string	string
predefined-tsrules	5.4.3.17	object	object
predefined-group-of-tsrules	5.4.3.18	object	object
ts-rule-base-name	5.4.3.19	string	string
NOTE 1: The basic JSON value types are defined in IETF RFC 7159 [15]. NOTE 2: The JCR types are defined in IETF draft-newton-json-content-rules [16]. NOTE 3: Fields marked with a supported feature are applicable as described in subclause 5.3.6. NOTE 4: The regular expression for a string type. NOTE 5: The quoted strings for a string type.

5.4.3.2 session-id

The session-id field is of type string, and contains the session id allocated by the PCRF. The session id format is defined in subclause 5.3.4.

5.4.3.3 ue-ipv4

The ue-ipv4 field is of type string and ip4 literal as defined in IETF draft-newton-json-content-rules [16].

5.4.3.4 ue-ipv6-prefix

The ue-ipv6-prefix field is of type string and ip6 literal as defined in IETF draft-newton-json-content-rules [16]. The PCRF uses it to indicate the IPv6 prefix allocated for the user.

5.4.3.5 tsrules

The tsrules field is of type object. It contains all of the dynamic traffic steering rules defined in the JSON body.

The following defines the content of the dynamic traffic steering rule:

The ts-rule-name field shall be included within the dynamic traffic steering rule.

A precedence value may be included.

Either flow-information(s) or the tdf-application-identifier field shall be included within the dynamic traffic steering rule.

The ts-policy-identifier-ul field and/or the ts-policy-identifier-dl field shall be included. If the traffic steering policies are identical in both downlink and uplink directions, the values of the ts-policy-identifier-ul field and the ts-policy-identifier-dl field shall be identical.

Below are the JCR for the dynamic traffic steering rule:

$tsrule = // : {

$ts-rule-name,

$precedence ?,

( $flow-information | $tdf-application-identifier ),

( $ts-policy-identifier-ul | $ts-policy-identifier-dl | ( $ts-policy-identifier-ul, $ts-policy-identifier-dl ) )

}

5.4.3.6 ts-rule-name

The ts-rule-name is of type string, and it defines a name for traffic steering rule. For traffic steering rules provisioned by the PCRF, it uniquely identifies a traffic steering rule within one St session. For traffic steering rules pre-defined at the TSSF, it uniquely identifies a traffic steering rule within the TSSF.

5.4.3.7 precedence

The precedence is of type number. Its value ranges from 0 to 4294967295.

Within the tsrule JSON content, the precedence field determines the order for the service data flow detection/the application detection at the TSSF to perform traffic steering. A traffic steering rule with a lower precedence value shall be applied prior to a traffic steering rule with a higher precedence value.

NOTE: The precedence value range defined within the traffic steering rule is operator configurable.

5.4.3.8 tdf-application-identifier

The tdf-application-identifier is of type string. It references the application detection filter defined at the TSSF.

5.4.3.9 flow-information

The flow-information field is of type array. It is sent from the PCRF to the TSSF and contains the information for a single IP flow packet filter.

The flow-description, a tos-traffic-class, security-parameter-index and flow-label specify the parameters to be used for matching payload packets. One of these fields shall be present in the object. The flow-direction field shall also be included.

The JCR for the flow-information is as follows:

$flow-information = "flow-information" : [

{

$flow-description ?,

$tos-traffic-class ?,

$security-parameter-index ?,

$flow-label ?,

$flow-direction

} +

]

5.4.3.10 flow-description

The flow-description field is of type string, it defines a packet filter for an IP flow.

The content has the same encoding as the IPFilterRule AVP value as defined in IETF RFC 6733 [21]. All limitations applicable to the Flow-Description AVP in subclause 5.4.2 of 3GPP TS 29.212 [17] apply to this field.

5.4.3.11 tos-traffic-class

The tos-traffic-class field is of type string. It is encoded on two octets, and represented as a hex string. The first octet contains the IPv4 Type-of-Service or the IPv6 Traffic-Class field and the second octet contains the ToS/Traffic Class mask field. When used for traffic detection, it defines the packet marking information used for traffic detection in the TSSF.

5.4.3.12 security-parameter-index

The security-parameter-index field is of type string, and it contains the security parameter index of the IPSec packet.

5.4.3.13 flow-label

The flow-label field is of type string, and it contains the IPv6 flow label header field.

5.4.3.14 flow-direction

The flow-direction field is of type string with three enumerations. It indicates the direction(s) that a filter is applicable, downlink only, uplink only or both down- and uplink (bidirectional).

DOWNLINK

The corresponding filter applies for traffic to the UE.

UPLINK

The corresponding filter applies for traffic from the UE.

BIDIRECTIONAL

The corresponding filter applies for traffic both to and from the UE.

5.4.3.15 ts-policy-identifier-dl

The ts-policy-identifier-dl is of type string and contains a reference to a pre-configured traffic steering policy at the TSSF in the downlink direction.

5.4.3.16 ts-policy-identifier-ul

The ts-policy-identifier-ul is of type string and contains a reference to a pre-configured traffic steering policy at the TSSF in the uplink direction.

5.4.3.17 predefined-tsrules

The predefined-tsrules contains all of the predefined traffic steering rules in the session.

The ts-rule-name field uniquely identifies the traffic steering rule defined at the TSSF.

The JCR definition for the predefined traffic steering rule is as follows:

$predefined-tsrule = // : {

ts-rule-name

}

5.4.3.18 predefined-group-of-tsrules

The predefined-group-of-tsrules field is of type object and contains the groups of the predefined traffic steering rules in the session.

The ts-rule-base-name field uniquely identifies the group of predefined traffic steering rules at the TSSF.

The JCR definition for the group of the dynamic traffic steering rules:

$predefined-group-of-tsrule = // : {

ts-rule-base-name

}

5.4.3.19 ts-rule-base-name

The ts-rule-base-name field is of type string, and it indicates the name of a predefined group of traffic steering rules residing at the TSSF.

5.4.3.20 called-station-id

The called-station-id is of type string, and it defines the address the user is connected to (i.e. the PDN identifier). For GPRS and EPS the APN. When used to contain the APN, the APN is composed of the APN Network Identifier only, or the APN Network Identifier and the APN Operator Identifier as specified in 3GPP TS 23.003 [20], subclause 9.1. The inclusion of the APN Operator Identifier can be configurable.

5.4.4 JSON errors and informational response fields

5.4.4.1 General

Table 5.4.4.1.1 describes the JSON fields defined for the errors and informational responsesincluding their types and the filed names.

Table 5.4.4.1.1: JSON fields for errors and informational response


Field Name	Subclause defined	JSON Value Type (NOTE 1)	JCR Type (NOTE 2)
errors	5.4.4.2	array	array
error-type	5.4.4.3	string	"application" "interface" "server" "other" (NOTE 3)
error-message	5.4.4.4	string	string
error-tag	5.4.4.5	string	string
error-path	5.4.4.6	string	string
error-info	5.4.4.7	object	object
success-message	5.4.4.8	string	string
success-path	5.4.4.9	string	string
success-info	5.4.3.10	object	object
NOTE 1: The basic JSON value types are defined in IETF RFC 7159 [10]. NOTE 2: The JCR types are defined in IETF draft-newton-json-content-rules [16]. NOTE 3: The quoted strings for a string type.

5.4.4.2 errors

The errors field is of type array, and it contains a list of errors. Each error is defined as an object in the array. This field shall be present when the TSSF responds with error(s) back to an HTTP request initiated by the PCRF.

An error object shall contain the error-type field and the error-message.

Optionally, it may include the error-tag field, error-path field and error-info field for further details. The error tag is used to classify a special error from other errors. The error-path is used to identify which resource has the error. The error-info is provided for additional information.

The JCR format:

$errors = "errors" : [

{

$error-type,

$error-message,

$error-tag ?,

$error-path ?,

$error-info ?

} +

]

5.4.4.3 error-type

The error-type field is of type string. It can be one of ‘application’, ‘interface’, ‘server’ and ‘other’.

When an error is related to the application processing in the TSSF, the error type shall be specified as ‘application’. When the error is a protocol compliance error, ‘interface’ shall be used. A server failure is represented with the ‘server’ error type. For all other errors, the ‘other’ error type shall be used.

5.4.4.4 error-message

The error-message field is of type string. It is a textual description of the error.

5.4.4.5 error-tag

The error-tag field is of type string. It defines a tag for a particular error.

TS_RULE_EVENT

This error-tag shall be used when the traffic steering rules cannot be installed/activated at the TSSF. Affected traffic steering rules shall be provided in the error-info with a sub field named ts-rule-reports including the reason and status of the rules as described insubclause 5.4.5.

5.4.4.6 error-path

The error-path field is of type string. It shall contain a JSON pointer as defined in IETF RFC 6901 [15] pointing to a resource where the error occurs.

5.4.4.7 error-info

The error-info field is defined as an object type. It represents informational details regarding the error.

5.4.4.6 success-message

The success-message is of type string. When included in the JSON body of an HTTP response, it shall be included under the root level of the JSON content.

5.4.4.7 success-path

The success-path field is of type string. It is a JSON pointer as defined in IETF RFC 6901 [15] pointing to the resource that was successfully operated on. It is an optional root level field provided along with a success-message field.

5.4.4.8 success-info

The success-info field is defined as an object type. It may include any additional information under the root level of the JSON content for an informational response.

5.4.5 JSON report fields

5.4.5.1 General

Table 5.4.5.1.1 describes the JSON fields defined for the report information objects which are included in the error-info field or the notification-info field.

Table 5.4.5.1.1: JSON fields for Report from the TSSF


Field Name	Subclause defined	JSON Value Type (NOTE 1)	JCR Type (NOTE 2)
ts-rule-reports	5.4.5.2	array	array
resource-paths	5.4.5.3	array	array
rule-status	5.4.5.4	string	string
rule-failure-code	5.4.5.5	string	string
NOTE 1: The basic JSON value types are defined in IETF RFC 7159 [10]. NOTE 2: The JCR types are defined in IETF draft-newton-json-content-rules [16].

5.4.5.2 ts-rule-reports

The ts-rule-reports field is of type array and it contains a list of traffic steering rule reports.

The ts-rule-reports field can be used in an HTTP response to report failures in the installation/activation of traffic steering rules. In this case, it shall be provided as a sub field of the error-info field.

The ts-rule-reports field can also be used in a HTTP request from the TSSF to notify the PCRF about enforcement failures of traffic steering rules. In this case, it shall be provided as a sub field of the notification-info field.

Multiple traffic steering rule report instances shall be provided within the ts-rule-reports field if different rule-status or rule-failure-code values are applicable within the same HTTP response or notification.

A report instance shall contain the resource-paths, rule-status and rule-failure-code fields.

The JCR format for the ts-rule-reports is:

$ts-rule-reports = "ts-rule-reports" : [

{

$resource-paths,

$rule-status,

$rule-failure-code

} +

]

5.4.5.3 resource-paths

The resource-paths field is of type array of strings. Each string shall be a JSON pointer as defined in IETF RFC 6901 [15].

Each JSON pointer within the resource-paths field shall be a reference to a specific traffic steering rule or to a group of traffic steering rules which cannot be installed/activated or enforced at the TSSF.

5.4.5.4 rule-status

The rule-status is of type string and shall contain one of the string representations of the PCC-Rule-Status AVP values as defined in subclause 5.3.19 of 3GPP TS 29.212 [17].

NOTE: For the current release, only the INACTIVE value is used.

5.4.5.5 rule-failure-code

The rule-failure-code is of type string.

The following values defined in the Rule-Failure-Code AVP in subclause 5.3.38 of 3GPP TS 29.212 [17] are applicable for traffic steering rule errors.

UNKNOWN_RULE_NAME

GW/PCEF_MALFUNCTION

RESOURCES_LIMITATION

MISSING_FLOW_INFORMATION

INCORRECT_FLOW_INFORMATION

TDF_APPLICATION_IDENTIFIER_ERROR

FILTER_RESTRICTIONS

The following value defined in the Rule-Failure-Code AVP is reused for traffic steering rule errors, however with a different explanation:

RESOURCE_ALLOCATION_FAILURE

This value is used to indicate that the traffic steering rule could not be successfully installed or maintained since the resources or services of the traffic steering control specified by the rule cannot be reserved in the TSSF and/or the (S)Gi-LAN; or those resources or services were released in the TSSF and/or the (S)Gi-LAN, for example, due to the switch eviction mechanism.

In addition, the following values are added:

RESOURCE_TIMEOUT

This value is used to indicate that the traffic steering rule could not be successfully installed or maintained since the booked resources or services of the traffic steering control specified by the rule have expired in the TSSF and/or the (S)Gi-LAN; for example, due to the flow expiry mechanism in the switches.

TS_POLICY_IDENTIFIER_ERROR

This value is used to indicate that the rule could not be successfully installed or enforced because both the ts-policy-identifier-dl and ts-policy-identifier-dl are invalid, unknown, or not applicable to the downlink and uplink traffic flows for the traffic steering control.

TS_POLICY_IDENTIFIER_DL_ERROR

This value is used to indicate that the rule could not be successfully installed or enforced because the ts-policy-identifier-dl is invalid, unknown, or not applicable to the downlink traffic flows for the traffic steering control.

TS_POLICY_IDENTIFIER_UL_ERROR

This value is used to indicate that the rule could not be successfully installed or enforced because the ts-policy-identifier-ul is invalid, unknown, or not applicable to the uplink traffic flows for the traffic steering control.

5.4.6 JSON notification fields

5.4.6.1 General

Table 5.4.6.1.1 describes the JSON fields defined for the notification HTTP messages from the TSSF to the PCRF, including their JSON value types, and JCR types as well.

Table 5.4.6.1.1: JSON fields for notifications from the TSSF


Field Name	Subclause defined	JSON Value Type (NOTE 1)	JCR Type (NOTE 2)
notifications	5.4.6.2	array	array
notification-type	5.4.6.3	string	"application" "other" (NOTE 3)
notification-message	5.4.6.4	string	String
notification-tag	5.4.6.5	string	String
notification-info	5.4.6.6	object	Object
NOTE 1: The basic JSON value types are defined in IETF RFC 7159 [10]. NOTE 2: The JCR types are defined in IETF draft-newton-json-content-rules [16]. NOTE 3: The quoted strings for a string type.

5.4.6.2 notifications

The notifications field is of type array, and it contains a list of notifications provided by the TSSF. Each notification is defined as an object in the array.

A notification object shall contain the notification-type and the notification-message fields.

Optionally, it may include the notification-tag and notification-info fields. The notification-tag is used to distinguish a specific notification from others. The notification-info is provided for additional information.

The JCR format of the notifications is as follows:

$notifications = "notifications" : [

{

$notification-type,

$notification-message,

$notification-tag ?,

$notification-info ?

} +

]5.4.6.3 notification-type

The notification-type field is of type string. It can be one of ‘application’ or ‘other’.

When a notification is due to a change to one of the St session resources/sub-resources, the type shall be specified as ‘application’. For all other notifications, the ‘other’ type shall be used.

5.4.6.4 notification-message

The notification-message field is of type string. It is a textual description of the notification.

5.4.6.5 notification-tag

The notification-tag field is of type string. It defines a tag for a particular notification.

TS_RULE_EVENT

This notification-tag value shall be used when the traffic steering rules cannot be enforced at the TSSF. Affected traffic steering rules shall be provided by the TSSF in the notification-info with a sub field named ts-rule-reports including the report reason and status of the rules.

5.4.6.6 notification-info

The notification-info field is defined as an object type. It represents informational details regarding the notification.

5.5 TSSF discovery

The TSSF URI is pre-configured on the PCRF, e.g. per PCEF.