6 API Definitions

29.5593GPP5G ProSe Key Management Services5G SystemRelease 17Stage 3TS

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

6.1 Npkmf_PKMFKeyRequest Service API

6.1.1 Introduction

The Npkmf_PKMFKeyRequest shall use the Npkmf_PKMFKeyRequest API.

The API URI of the Npkmf_PKMFKeyRequest 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 [6], i.e.:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>

with the following components:

– The {apiRoot} shall be set as described in 3GPP TS 29.501 [6].

– The <apiName> shall be "npkmf-keyrequest ".

– 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 [8], shall be used as specified in clause 5 of 3GPP TS 29.500 [5].

HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [5].

The OpenAPI [7] specification of HTTP messages and content bodies for the Npkmf_PKMFKeyRequest 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 [5] for the usage of HTTP standard headers.

6.1.2.2.2 Content type

JSON, IETF RFC 8259 [9], 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 [5]. 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 [10].

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 [5] shall be applicable, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [5] may be supported.

6.1.3 Resources

6.1.3.1 Overview

This clause describes the structure for the Resource URIs and the resources and methods used for the service.

Figure 6.1.3.1-1 describes the resource URI structure of the Npkmf_PKMFKeyRequest API.

Figure 6.1.3.1-1: Resource URI structure of the Npkmf_PKMFKeyRequest 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

ProSe Keys Collection

/prose-keys

request

(POST)

ProseKey service operation

6.1.3.2 Resource: ProSe Keys Collection

6.1.3.2.1 Description

This resource represents the collection of the ProSe Keys managed by the PKMF.

This resource is modelled with the Collection resource archetype (see clause C.2 of 3GPP TS 29.501 [5]).

6.1.3.2.2 Resource Definition

Resource URI: {apiRoot}/<apiName>/<apiVersion>/prose-keys

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

There is no standard method supported by the 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

Operation name	Custom operaration URI	Mapped HTTP method	Description
request	{resourceUri}/request	POST	ProseKey service operation

6.1.3.2.4.2 Operation: request

6.1.3.2.4.2.1 Description

This custom operation requests the keying material related to 5G ProSe in the PKMF.

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
ProseKeyReqData	M	1	Representation of the input to request the keying material.

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
ProseKeyRspData	M	1	200 OK	Representation of the successfully requested keying material.
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 a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same PKMF or PKMF (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 a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same PKMF or PKMF (service) set. (NOTE 2)
ProblemDetails	O	0..1	403 Not Found	The "cause" attribute shall be set to one of the following application error: – UE_NOT_AUTHORIZED See table 6.1.7.3-1 for the description of these errors.
ProblemDetails	O	0..1	404 Not Found	The "cause" attribute shall be set to one of the following application error: – UE_NOT_FOUND See table 6.1.7.3-1 for the description of these errors.
NOTE1: The manadatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [5] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.1.3.2.4.2.2-3: 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 PKMF or PKMF (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 PKMF (service) instance ID towards which the request is redirected

Table 6.1.3.2.4.2.2-4: 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 PKMF or PKMF (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 PKMF (service) instance ID towards which the request is redirected

6.1.4 Custom Operations without associated resources

There is no custom operation without associated resources supported in Npkmf_PKMFKeyRequest Service.

6.1.5 Notifications

There is no notification defined for Npkmf_PKMFKeyRequest 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 Npkmf_PKMFKeyRequest service based interface protocol.

Table 6.1.6.1-1: Npkmf_PKMFKeyRequest specific Data Types

Data type	Clause defined	Description	Applicability
ProseKeyReqData	6.1.6.2.2	Representation of the input to request the keying material.
ProseKeyRspData	6.1.6.2.3	Representation of the successfully requested keying material.
PrukId	6.1.6.3	User Plane Prose Remote User Key ID
Knrp	6.1.6.3	Key for NR PC5
KnrpFreshnessParameter1	6.1.6.3	K_NRP Freshness Parameter 1
KnrpFreshnessParameter2	6.1.6.3	K_NRP Freshness Parameter 2
Gpi	6.1.6.3	GBA Push Information

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

Table 6.1.6.1-2: Npkmf_PKMFKeyRequest re-used Data Types

Data type	Reference	Comments	Applicability
RelayServiceCode	3GPP TS 29.571 [15]	Relay Service Code
ResynchronizationInfo	3GPP TS 29.503 [17]	Resynchronization Information
Suci	3GPP TS 29.509 [18]	String contains the SUCI

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: ProseKeyReqData

Table 6.1.6.2.2-1: Definition of type ProseKeyReqData

Attribute name	Data type	P	Cardinality	Description	Applicability
relayServCode	RelayServiceCode	M	1	This IE shall indicate the Relay Service Code from the 5G ProSe Remote UE.
knrpFreshness1	KnrpFreshnessParameter1	M	1	This IE shall carry the K_NRP Freshness Parameter 1 in the 5G ProSe Remote UE.
resyncInfo	ResynchronizationInfo	C	0..1	This IE shall be present in service request for subsequent key request handling synchronization failure. When present, this IE shall carry information (RAND, AUTS) from the 5G ProSe Remote UE related to the synchronization Failure.
prukId	PrukId	C	0..1	This IE may be present in service request for initial key request. When present, this IE shall indicate the UP-PRUK ID from the 5G ProSe Remote UE. (See NOTE)
suci	Suci	C	0..1	This IE may be present in service request for initial key request. When present, this IE shall carry the SUCI of the 5G ProSe Remote UE (See NOTE).
NOTE: Either prukId IE or suci IE shall be present in service request for initial key request.

6.1.6.2.3 Type: ProseKeyRspData

Table 6.1.6.2.3-1: Definition of type ProseKeyRspData

Attribute name	Data type	P	Cardinality	Description	Applicability
knrp	Knrp	M	1	This IE shall carry the K_NRP derived by the PKMF.
knrpFreshness2	KnrpFreshnessParameter2	M	1	This IE shall carry the K_NRP Freshness Parameter 2 generated by the PKMF.
gpi	Gpi	C	0..1	This IE shall be present if GPI is generated or requested. When present, this IE shall carry the GPI.

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
PrukId	string	User Plane Prose Remote User Key ID String type as defined in OpenAPI Specification [7], carrying the value of the "UP-PRUK ID" parameter via PC8 (with "xs:string" type in XML schema) as specified in clause 11.6.2.3 of 3GPP TS 24.554 [16].
Knrp	string	Key for NR PC5 String type as defined in OpenAPI Specification [7], carrying the value of the "KNRP" parameter via PC8 (with "xs:hexBinary" type in XML schema) as specified in clause 11.6.2.25 of 3GPP TS 24.554 [16].
KnrpFreshnessParameter1	string	K_NRP Freshness Parameter 1 String type as defined in OpenAPI Specification [7], carrying the value of the "KNRP freshness parameter 1" parameter via PC8 (with "xs:hexBinary" type in XML schema) as specified in clause 11.6.2.22 of 3GPP TS 24.554 [16].
KnrpFreshnessParameter2	string	K_NRP Freshness Parameter 2 String type as defined in OpenAPI Specification [7], carrying the value of the "KNRP freshness parameter 2" parameter via PC8 (with "xs:hexBinary" type in XML schema) as specified in clause 11.6.2.26 of 3GPP TS 24.554 [16].
Gpi	string	GBA Push Information String type as defined in OpenAPI Specification [7], carrying the value of the "GPI" parameter via PC8 (with "xs:hexBinary" type in XML schema) as specified in clause 11.6.2.16 of 3GPP TS 24.554 [16].

6.1.6.4 Data types describing alternative data types or combinations of data types

There is no data type describing alternative data types or combinations of data types in Npkmf_PKMFKeyRequest Service.

6.1.6.5 Binary data

There is no binary data type in Npkmf_PKMFKeyRequest Service.

6.1.7 Error Handling

6.1.7.1 General

For the Npkmf_PKMFKeyRequest API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [6]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [5] 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 [5].

In addition, the requirements in the following clauses are applicable for the Npkmf_PKMFKeyRequest API.

6.1.7.2 Protocol Errors

Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [5].

6.1.7.3 Application Errors

The application errors defined for the Npkmf_PKMFKeyRequest service are listed in Table 6.1.7.3-1.

Table 6.1.7.3-1: Application errors

Application Error	HTTP status code	Description
UE_NOT_AUTHORIZED	403 Forbidden	The UE is not authorized for the requested service.
UE_NOT_FOUND	404 Not Found	The UE indicated by the SUCI or related to the UP-PRUK ID is not found in the PKMF.

6.1.8 Feature negotiation

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

Table 6.1.8-1: Supported Features

Feature number	Feature Name	Description
N/A

6.1.9 Security

As indicated in 3GPP TS 33.501 [11] and 3GPP TS 29.500 [5], the access to the Npkmf_PKMFKeyRequest 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.

If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Npkmf_PKMFKeyRequest API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [13], 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 Npkmf_PKMFKeyRequest service.

The Npkmf_PKMFKeyRequest API defines a single scope "npkmf-keyrequest" for OAuth2 authorization (as specified in 3GPP TS 33.501 [11]) for the entire service, and it does not define any additional scopes at resource or operation level.

6.1.10 HTTP redirection

An HTTP request may be redirected to a different 5G PKMF service instance, within the same 5G PKMF or a different 5G PKMF of an 5G PKMF set, e.g. when an 5G PKMF service instance is part of an 5G PKMF (service) set or when using indirect communications (see 3GPP TS 29.500 [5]).

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

If an 5G PKMF within an 5G PKMF set redirects a service request to a different 5G PKMF of the set using an 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new 5G PKMF 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 [5].

Annex A (normative):
OpenAPI specification