Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 33.122  Word version:  16.3.0

Top   Top   Up   Prev   None
1…   4…   5…   A…

 

A (Normative)  Key derivation functionsWord‑p. 21

A.1  AEFPSK derivation function

AEF PSK key derivation shall be performed using the key derivation function (KDF) specified in TS 33.220. This subclause specifies how to construct the input string, S, to the KDF (which is input together with the relevant key).
The FC number space is controlled by TS 33.220.
AEF PSK shall be derived by the API invoker and the CAPIF core function based on Service API interface information and CAPIF‑1e TLS session parameters. Length and format of TLS session parameters used for key derivation are as specified in TLS. Security profiles for TLS implementation and usage shall follow the provisions given in TS 33.310, Annex E.
The following parameters shall be used to form the input S to the KDF.
FC = 0x7A
P0 = Service API interface information
L0 = Length of Service API interface information
P1 = CAPIF‑1e TLS session's Session ID, generated as part of TLS full Handshake.
L1 = Length of TLS Session ID
The input key shall be equal to CAPIF‑1e TLS session's Master Secret.
Up

B  Security flowsWord‑p. 22

B.1  Onboarding

Figure B.1-1 shows the functional security flow for online onboarding. Offline onboarding is out of scope for the present document.
[not reproduced yet]
Figure B.1-1: Onboarding security flow
Up
As a pre-requisite to onboarding, the API Invoker and the CAPIF are provisioned with the necessary onboarding enrolment information for the API Invoker. The method to do this is out of scope for the present document.
Initially, the API Invoker attempts to establish a secure connection with the CAPIF core. If the onboarding session cannot be secured, the session is released and the onboarding flow ends.
If the session is secured, the API Invoker requests onboarding using the Onboard API Invoker Request message defined in clause 8.1 of TS 23.222. The API Invoker includes an onboarding credential in the Onboard API Invoker Request message. The CAPIF core receives the Onboard API Invoker request message and validates the onboarding credential. If the onboarding credential is valid, the CAPIF core creates and returns an Onboard API Invoker Response message defined in clause 8.1 of TS 23.222, which contains the API Invoker profile and includes the API Invoker ID. Security information for CAPIF‑1 or CAPIF‑1e authentication and (optionally) security information for CAPIF‑2 or CAPIF‑2e is also transferred to the API Invoker as part of the onboarding response. If the CAPIF core cannot validate the onboarding credentials, then an Onboard API Invoker response message containing an error response is returned to the API Invoker instead.
Following the return of an Onboard API Invoker response message (either successful or unsuccessful), the secure session is torn down and the onboarding security flow ends.
Up

B.2  Authentication and authorizationWord‑p. 23
CAPIF authentication and authorization consists of CAPIF‑1e authentication and CAPIF‑2e authentication and authorization. Figure B.2-1 shows the functional security flow for CAPIF‑1e authentication while Figure B.2-2 shows the functional security flow for CAPIF‑2e authentication and authorization.
Prior to starting the security flow for either CAPIF‑1e or CAPIF‑2e authentication and authorization, successful onboarding of the API Invoker has taken place.
In figure B.2-1, the security flow starts with the API Invoker establishing a TLS connection to the CAPIF core over the CAPIF‑1e interface per clause 6.3. Successful TLS establishment results in the opportunity for the CAPIF core to transfer CAPIF‑2e AEF authentication and authorization information to the API invoker. After transfer of the CAPIF‑2e AEF authentication and authorization information to the API invoker, the TLS session is released and the CAPIF‑1e security flow ends.
In the case that either the CAPIF‑1e TLS session or API invoker authentication procedure fails, the API Invoker authentication is rejected, AEF authentication and authorization information is not transferred to the API Invoker, and the TLS session with the API Invoker is closed.
[not reproduced yet]
Figure B.2-1: CAPIF‑1e authentication
Up
Figure B.2-2 shows the security flow for the CAPIF‑2e interface. Successful CAPIF‑1e authentication and AEF authentication information (as a minimum) is needed for the API invoker to communicate with the AEF.
The security flow begins when the API Invoker makes an authentication request to the AEF. The AEF receives the request and attempts to authenticate the API Invoker. If the AEF does not possess the authentication information to authenticate the API invoker, the AEF can query the CAPIF core for it. If authentication of the API invoker is successful, then a TLS session is established. If authentication of the API invoker fails, the security flow ends.
If authentication of the API invoker is successful, then based on the interested service API, the API Invoker makes a northbound API request.
The AEF attempts to validate the northbound API request. If the AEF does not possess the authorization information for the requested service API, the AEF can query the CAPIF core for it. If validation of the northbound API request is successful, the northbound API is serviced.
Upon completion of the northbound API action(s), the secure session is torn down and the security flow ends.
If the AEF cannot validate the northbound API request, the AEF rejects the northbound API request, tears down the secure session, and ends the security flow.
[not reproduced yet]
Figure B.2-2: CAPIF‑2e authentication and authorization
Up

C (Normative)  Access token profile for 'Method 3 - TLS with OAuth token'Word‑p. 26

C.1  General

The information in this annex provides a description of the access token used in the 'Method 3 - TLS with OAuth token' authentication and authorisation method (see clause 6.5.2.3). Characterization of the access token, how to obtain the access token, how to validate the access token, and how to refresh the access token is explained.
A 'Method 3 - TLS with OAuth token' access token has the following chanracterics:
  • Shall be encrypted when transported over the CAPIF 1/1e and CAPIF 2/2e interfaces (e.g. using TLS);
  • Shall be a bearer type as specified in RFC 6750;
  • Shall be encoded as a JSON Web Token as specified in RFC 7519;
  • Shall be protected by the JSON signature profile as specified in RFC 7515; and,
  • Shall be validated per OAuth 2.0 [4], RFC 7519 and RFC 7515.
Up

C.2  Access token profile

C.2.1  General

The 'Method 3 - TLS with OAuth token' access token contains the token claims described in C.2.2. Token claims are provided by the CAPIF Core Function and contain authentication and authorization information about the API Invoker. Token claims are used by the API Exposing Function for authorization of API Invoker northbound API requests.

C.2.2  Token claims

The CAPIF 'Method 3 - TLS with OAuth token' access token shall convey the following claims as defined in RFC 7519 and RFC 6749].
Parameter
Description

exp
REQUIRED. The expiration time of the access token. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew (not to exceed 30 seconds).
client_id
REQUIRED. The identifier of the API Invoker making the API request as previously established with the CAPIF Core Function through onboarding.
scope
REQUIRED. A string containing a space-delimited list, comprising of the following as scopes associated with this token:
  • List of Services per AEF, e.g.
    • "AEF1:Service1,Service2,Service3,...,ServiceX;
      AEF2:Service1,Service2,Service3,...,ServiceZ"

The 'exp'and 'scope' parameters of the access token shall be determined by the CAPIF core function based upon the client_id of the API Invoker provided in the Access Token Request message.
The scope parameter 'List of Services per AEF' shall contain a full or partial list of services which the API Invoker is permitted to access at each AEF.
Up

C.3  Obtaining tokensWord‑p. 27

C.3.1  General

Once an API Invoker has successfully performed onboarding with the CAPIF Core Function, the API Invoker may request access tokens using 'Method 3 - TLS with OAuth token' defined in clause 6.5.2.3. Figure C.3.1-1 shows the access token request and access token response message exchange.
[not reproduced yet]
Figure C.3.1-1: Requesting an access token
Up

C.3.2  Access token request

To obtain an access token, the API Invoker makes a request to the CAPIF Core Function by sending an Access Token Request message with the following parameters using the "application/x-www-form-urlencoded" format, with a character encoding of UTF-8 in the HTTP request entity-body. The access token request parameters are shown in table C.3.2-1.
Parameter
Values

grant_type
REQUIRED. The value shall be set to "client_credentials".
client_id
REQUIRED. The identifier of the API Invoker making the request. It shall match the value that was assigned to the API Invoker during the onboarding process.
client_cred
OPTIONAL. The client credential that was provided to the API Invoker during the onboarding process.
scope
OPTIONAL. A string containing a space-delimited list, comprising of the following as scopes associated with this token:
  • List of Services per AEF, e.g.
    • "AEF1:Service1,Service2,Service3,...,ServiceX;
      AEF2:Service1,Service2,Service3,...,ServiceZ"

Up

C.3.3  Access token responseWord‑p. 28
If the access token request (i.e. the client credential) is valid and authorized by the CAPIF Core Function, the CAPIF Core Function then returns an access token to the API Invoker in an access token response message; otherwise it will return an error.
The access token response parameters are shown in table C.3.3-1.
Parameter
Values

access_token
REQUIRED. This is the issued access token.
token_type
REQUIRED. This field shall be "bearer"
expires_in
REQUIRED. The lifetime in seconds of the access token.
scope
OPTIONAL. The granted scope by the CAPIF core function.

Upon receiving the access token reponse message, the API Invoker may now use the access token to make authorized northbound API requests to API Exposure Functions as described in clause 6.5.2.3.
Up

C.4  Refreshing an access token

To protect against leakage or other compromise, an access token includes an expiration time. If the API Invoker determines that its access token has expired or if the API Invoker receives an indication from the AEF that a fresh access token is needed, the API Invoker shall return to the CAPIF Core Function and repeat the procedure defined in clause C.3.

C.5  Using the token to access API exposing functions

Access tokens of type "bearer" shall be communicated from the API Invoker to AEF by including the access token in the HTTP Authorization Header, per RFC 6750.
The access token is opaque to the API Invoker, meaning that the API Invoker does not have any specific knowledge of the access token itself. The API Invoker shall use the 'expires_in' parameter from the access token response message to determine whether the access token is valid so that it does not send an expired access token to AEFs. If the access token is presented to an AEF and the token is expired or revoked, the AEF should return an error message indicating such to the API Invoker.
Up

C.6  Token revocation

In order to limit the time validity of a token, the "exp" and "expires_in" parameters shall be used as a method of access token revocation.
Within the claims of a 'Method 3 - TLS with OAuth token' access token, the "exp" parameter shall be used by the AEF to determine whether or not the token has expired. If the current time is beyond the time specified by the "exp" parameter, the associated token shall no longer be considered valid and any requests made with an expired token shall be rejected by the AEF.
Within the claims of an access token response message, the "expires_in" parameter shall be used by the API Invoker to determine validity of the associated token. If the current time is beyond the time specified by the "expires_in" parameter, the associated access token shall no longer be considered valid and no northbound API requests shall be made using the expired access token. The procedure defined in C.3 shall be used to obtain a new access token.
Up

C.7  Token validationWord‑p. 29

C.7.1  Access token validation

A 'Method 3 - TLS with OAuth token' access token shall be validated according to RFC 7519.

$  Change historyWord‑p. 30

Up   Top