Content for TS 33.122 Word version: 17.1.0
6 Security procedures
6.1 Security procedures for API invoker onboarding
6.2 Security procedures for CAPIF-1 reference point
6.3 Security procedures for CAPIF-1e reference point
6.4 Security procedures for CAPIF-2 reference point
6.5 Security procedures for CAPIF-2e reference point
6.6 Security procedures for CAPIF-3/4/5 reference points
6.7 Security procedures for updating security method
6.8 Security procedure for API invoker offboarding
6.9 Security procedures for CAPIF-7/7e reference points
6.10 Security procedures for CAPIF-3e/4e/5e reference points
6 Security procedures p. 10
6.1 Security procedures for API invoker onboarding p. 10
The API invoker and the CAPIF core function shall follow the procedure in this subclause to secure and authenticate the onboarding of the API invoker to the CAPIF core function. The API invoker and the CAPIF core function shall establish a secure session using TLS. Security profiles for TLS implementation and usage shall follow the provisions given in TS 33.310, Annex E.
With a secure session established, the API Invoker sends an Onboard API Invoker Request message to the CAPIF core function. The Onboard API Invoker Request message carries an onboard credential obtained during pre-provisioning of the onboard enrolment information, which may be an OAuth 2.0 [4] access token. When the OAuth 2.0 token based mechanism is used as the onboarding credential, the access token shall be encoded as JSON web token as specified in RFC 7519, shall include the JSON web signature as specified in RFC 7515, and shall be validated per OAuth 2.0 [4], RFC 7519 and RFC 7515. Other credentials may also be used (e.g. message digest). Figure 6.1-1 details the security information flow for the API invoker onboarding procedure. The OAuth 2.0 token based authentication credential is shown in this example.
Step 1.
As a prerequisite to the onboarding procedure, the API invoker obtains onboarding enrolment information from the API provider domain. The onboarding enrolment information is used to authenticate and establish a secure TLS communication with the CAPIF core function during the onboarding process. The enrolment information includes details of the CAPIF core function (Address, and Root CA certificate) and includes an onboarding credential (the OAuth 2.0 [4] access token).
Step 2.
The API invoker and CAPIF core function shall establish a secure session based on TLS (Server side certificate authentication). The API invoker shall use the enrolment information obtained in step 1 to establish the TLS session with the CAPIF core function.
Step 3.
After successful establishment of the TLS session, the API invoker shall send an Onboard API invoker request message to the CAPIF core function along with the enrolment credential (OAuth 2.0 [4] access token). The API invoker generates the key pair {Private Key, Public key} and provides the public key along with the Onboard API invoker request.
Step 4.
The CAPIF core function shall validate the enrolment credential (OAuth 2.0 [4] access token). If validation of the credential (the OAuth 2.0 [4] access token in this example) is successful, the CAPIF core function shall generate an API invoker's profile as specified in TS 23.222 which may contain the selected method for AEF authentication and authorization between the API Invoker and the AEF (see subclause 6.5.2). The CAPIF core function may generate API invoker's certificate on its own, for the assigned API invoker identity and public key. This certificate shall be used by the API invoker for subsequent authentication procedures with the CAPIF core function and may be used for establishing a secure connection and authentication with the API Exposing Function. The CAPIF core function may optionally generate an Onboard_Secret if the subscribed Service API uses Method 3 (as specified in clause 6.5.2.3 of the present document) for CAPIF-2e security. The Onboard_Secret value remains the same during the lifetime of the onboarding, and shall be bound to the CAPIF core function specific API Invoker ID.
Step 5.
The CAPIF core function shall respond with an Onboard API invoker response message. The response shall include the CAPIF core function assigned API invoker ID, AEF Authentication and authorization information (if generated in step 4), API invoker's certificate and the API invoker Onboard_Secret (if generated by the CAPIF core function).
6.2 Security procedures for CAPIF-1 reference point p. 12
TLS shall be used to provide integrity protection, replay protection and confidentiality protection. The support of TLS is mandatory and optional to use based on the domain administrator's policy to protect interfaces within the trusted domain.
The procedure in subclause 6.3 of the present document shall be followed unless the security of CAPIF-1 reference point is provided by other means.
6.3 Security procedures for CAPIF-1e reference point p. 12
6.3.1 Authentication and authorization p. 12
6.3.1.1 General p. 12
For authentication of the CAPIF-1e reference point, mutual authentication based on client and server certificates shall be performed between the CAPIF core function and the API invoker, using TLS.
Certificate based authentication shall follow the profiles given in clauses 6.1.3a and 6.1.4a of TS 33.310. The structure of the PKI used for the certificate is out of scope of the present document.
TLS [9] shall be used to provide integrity protection, replay protection and confidentiality protection for CAPIF-1e interface. The support of TLS on CAPIF-1e interface is mandatory. Security profiles for TLS implementation and usage shall follow the provisions given in TS 33.310, Annex E.
6.3.1.2 Security method negotiation p. 12
The API invoker and the CAPIF core function shall negotiate a security method that shall be used by the API invoker and the API exposing function for CAPIF-2e interface authentication and protection. After successful mutual authentication on CAPIF-1e interface, based on the API invoker's subscribed service APIs, access scenarios (whether the API invoker access the AEF prior to service API invocation or upon the service API invocation) and AEF capabilities, the CAPIF core function shall choose the security method and sends the chosen security methods along with the information required for authentication of the API invoker at the AEF to the API invoker. The information may include the validity time of the CAPIF-2e credentials. This is depicted in Figure 6.3.1-1.
Pre-conditions:
Step 1.
The API invoker is onboarded with the CAPIF core function.
Figure 6.3.1-1: Selection of security method to be used in CAPIF-2/2e reference point
(⇒ copy of original 3GPP image)
(⇒ copy of original 3GPP image)
Step 1.
Mutual authentication based on client and server certificates shall be established using TLS between the API invoker and the CAPIF core function. The client certificate that was provided to the API invoker as the result of successful onboarding is used based on the description in subclause 6.1 of the present document.
Step 2.
The API invoker may send CAPIF-2/2e security capability information to the CAPIF core function in the Security Method Request message, indicating the list of security methods that the API invoker supports over CAPIF-2/2e reference point for each AEF.
Step 3.
The CAPIF core function shall select a security method to be used over CAPIF-2/2e reference point for each requested AEF, taking into account the information from the API invoker in step 2, access scenarios and AEF capabilities.
Step 4.
The CAPIF core function shall send Security Method Response message to the API invoker, indicating the selected security method for each AEF, any security information related to the security method. The API invoker shall use this method in the subsequent communication establishment with the API exposing function over CAPIF-2/2e reference point, as described in subclause 6.5 of the present document.
6.3.1.3 API discovery p. 13
After successful authentication between API invoker and CAPIF core function, the CAPIF core function shall decide whether the API invoker is authorized to perform discovery based on API invoker ID and discovery policy.
6.3.1.4 Topology hiding p. 13
When topology hiding is enabled, the CAPIF core function shall respond to service APIs discovery requests with AEF information, which exposes the service API and acts as topology hiding entity.
6.4 Security procedures for CAPIF-2 reference point p. 13
TLS shall be used to provide integrity protection, replay protection and confidentiality protection. The support of TLS is mandatory and optional to use based on the domain administrator's policy to protect interfaces within the trusted domain.
The procedure in subclause 6.5 of the present document shall be followed unless the security of CAPIF-2 reference point is provided by other means.
If the domain administrator's policy to authorize the API invoker's service API invocation requests is set, the API invoker's authorization shall be performed according to the authorization mechanisms specified for CAPIF-2e reference point in subclause 6.5 of the present document.
6.5 Security procedures for CAPIF-2e reference point p. 14
6.5.1 General p. 14
Based on the selected security method by the CAPIF Core Function (c.f., subclause 6.3.1), one of the methods specified in subclause 6.5.2 shall be used by the API invoker and the API exposing function for CAPIF-2e interface authentication and protection.
6.5.2 Authentication and authorization p. 14
6.5.2.1 Method 1 - Using TLS-PSK p. 14
The API invoker and the API exposing function shall follow the procedure in this sub-clause to establish dedicated secure session using TLS connection based on Pre-Shared Key (PSK). CAPIF-1e authentication shall be used to bootstrap a Pre-Shared key for authenticating a TLS connection for CAPIF-2e. It is assumed that both the API invoker and the CAPIF core function are pre-provisioned with certificates. The TLS profile as specified in Annex E of TS 33.310 shall be used. Figure 6.5.2.1-1 details the message flow between the API invoker, the CAPIF core function and the API exposing function, to establish secure CAPIF-2e interface using a pre-shared key for authentication.
Figure 6.5.2.1-1: CAPIF-2e interface authentication and protection using TLS-PSK
(⇒ copy of original 3GPP image)
(⇒ copy of original 3GPP image)
Step 1.
After successful establishment of TLS on CAPIF-2e reference point, the API exposing function shall authorize the API invoker's service API invocation request based on authorization information obtained from CAPIF core function as specified in subclause 8.16 of TS 23.222.
CAPIF-1e authentication and secure session is established as specified in subclause 6.3.1 of the present document. The CAPIF core function shall provide the validity timer value for the key AEF PSK.
Step 2.
After successful establishment of TLS on CAPIF-1e, the API invoker and the CAPIF core function shall derive the key AEF PSK.
The Key AEF PSK shall be bound to an AEF and shall be derived as specified in Annex A. The API invokswer and the CAPIF core function starts the validity timer for the key AEF PSK.
Step 3.
The API Invoker shall send Authentication Initiation Request to the AEF, including the CAPIF core function assigned API invoker ID.
Steps 1 and 2 of this procedure may be skipped if the API invoker is already in possession of a valid key AEF PSK. In this case, the API invoker begins the procedure at step 3.
Step 4.
The AEF shall request for security information from the CAPIF Core Function to perform authentication and secure interface establishment with the API invoker, if the AEF does not have a valid key. The CAPIF Core Function provides the security information related to the chosen security method (TLS-PSK: AEF PSK) to the AEF over CAPIF-3 reference point. The CAPIF core function shall provide the remaining validity timer value for the key AEF PSK.
Step 5.
After fetching the relevant security information (AEF PSK) for the authentication, the AEF shall send Authentication Initiation Response message to API invoker to initiate the TLS session establishment. The AEF starts the validity timer based on the value received from the CAPIF core function in step 4.
Step 6.
The API Invoker and the AEF shall perform mutual authentication using the key AEF PSK and establish TLS session over the CAPIF-2e.
6.5.2.2 Method 2 - Using PKI p. 15
The API invoker and the API exposing function shall follow the procedure in this subclause to establish dedicated secure session over CAPIF-2e using TLS based on certificate based mutual authentication. It is assumed that both API invoker and API exposing function are pre-provisioned with certificates. Figure 6.5.2.2-1 details the message flow between the API invoker, the CAPIF core function and the API exposing function related to this security method.
Figure 6.5.2.2-1: CAPIF-2e interface authentication and protection using certificate based mutual authentication
(⇒ copy of original 3GPP image)
(⇒ copy of original 3GPP image)
Step 1.
After successful establishment of TLS on CAPIF-2e reference point, the API exposing function shall authorize the API invoker's service API invocation request based on authorization information obtained from CAPIF core function as specified in subclause 8.16 of TS 23.222.
The API invoker shall send Authentication Initiation Request to the AEF, including API invoker ID.
Step 2.
The AEF shall request for security information from the CAPIF Core Function to perform authentication and secure interface establishment with the API invoker. The CAPIF Core Function provides the security information related to the chosen security method (TLS-PKI) to the AEF over CAPIF-3 reference point. CAPIF core function may return API invoker's root CA certificate for the AEF to validate the API invoker's certificate.
Step 3.
After fetching the relevant security information for the authentication, AEF shall send Authentication Initiation Response message to API invoker to initiate the TLS session establishment procedure.
Step 4.
Then the API Invoker and the AEF shall perform mutual authentication using certificates and establish TLS session over the CAPIF-2e. Certificate based authentication shall follow the profiles given in clauses 6.1.3a and 6.1.4a of TS 33.310. The structure of the PKI used for the certificate is out of scope of the present document.
6.5.2.3 Method 3 - TLS with OAuth token p. 16
This method details establishment of secure channel over CAPIF-1e, CAPIF-2e reference points, and uses the OAuth 2.0 [4] token based mechanism to authorize and honour API invoker's northbound API invocations to the API exposing function. Figure 6.5.2.3-1 details security information flows between the API invoker, the CAPIF core function and the API exposing function. It is assumed that the API invoker, the CAPIF core function and the AEF are pre-provisioned with the appropriate credentials and related information to establish a secure session.
As per OAuth 2.0 [4], the CAPIF core function shall perform the functionality of the authorization server and provide the token endpoint, the API invoker shall perform the function of the client functionality, while the API exposing function shall perform the resource server functions. The API invoker client (client endpoint) shall be registered as a confidential client type with an authorization grant type of 'client credentials'. The authorization shall be previously arranged in the CAPIF core function. The access token shall follow the profile described in Annex C.
Figure 6.5.2.3-1: CAPIF-2e interface authentication and protection using Access Tokens
(⇒ copy of original 3GPP image)
(⇒ copy of original 3GPP image)
Step 1.
CAPIF-1e authentication and secure session establishment is performed as specified in subclause 6.3.1.
Step 2.
After successful establishment of TLS session over CAPIF-1e, as described in subclause 6.3.1 of the present document, the API invoker shall send an Access Token Request message to the CAPIF core function as per the OAuth 2.0 [4] specification.
Step 3.
The CAPIF core function shall verify the Access Token Request message per OAuth 2.0 [4] specification.
Step 4.
If the CAPIF core function successfully verifies the Access Token Request message, the CAPIF core function shall generate an access token specific to the API invoker and return it in an Access Token Response message.
Steps 1 to 4 of this procedure may be skipped if the API invoker is already in possession of a valid OAuth access token. In this case, the API invoker begins the procedure at step 5.
Step 5.
On CAPIF-2e, the API invoker authenticates to the AEF by establishing a TLS session with the API exposing function based on the authentication and authorization method (i.e. Server (AEF) side certificate authentication or certificate-based mutual authentication) as indicated by CAPIF core function. The following procedure shall be performed prior to establishment of TLS session.
The API invoker shall send Authentication Initiation Request to the AEF, including API invoker ID.
The AEF shall request for security information from the CAPIF Core Function to perform authentication and secure interface establishment with the API invoker. The CAPIF Core Function provides the security information related to the chosen security method (TLS with OAuth token) to the AEF over CAPIF-3 reference point. The CAPIF core function may return API invoker's root CA certificate for the AEF to validate the API invoker's certificate.
After fetching the relevant security information for the authentication, the AEF shall send Authentication Initiation Response message to API invoker to initiate the TLS session establishment procedure.
Step 6.
With successful authentication to the AEF on CAPIF-2e, the API invoker shall initiate invocation of a 3GPP northbound API with the AEF. The access token received from the CAPIF core shall be sent along with the northbound API invocation request as per OAuth 2.0 [4].
Step 7.
The API exposing function shall validate the access token. The AEF verifies the integrity of the access token by verifying the CAPIF core function signature If validation of the access token is successful, the AEF shall verify the API invoker's Northbound API invocation request against the authorization claims in access token, ensuring that the API Invoker has access permission for the requested service API.
Step 8.
After successful verification of the access token and authorization claims of the API invoker, the requested northbound API shall be invoked and the appropriate response shall be returned to the API invoker.
6.6 Security procedures for CAPIF-3/4/5 reference points p. 18
To ensure security of the interfaces between CAPIF entities within a trusted domain, namely CAPIF-3, CAPIF-4, CAPIF-5:
- TLS shall be used to provide integrity protection, replay protection and confidentiality protection. The support of TLS is mandatory. Security profiles for TLS implementation and usage shall follow the provisions given in TS 33.310, Annex E.
- Certificate based mutual authentication shall be performed between the CAPIF entities using TLS. Certificate based authentication shall follow the profiles given in clauses 6.1.3a and 6.1.4a of TS 33.310. The structure of the PKI used for the certificate is out of scope of the present document.
6.7 Security procedures for updating security method p. 18
As specified in TS 23.222, the CAPIF core function shall receive updates to AEF authentication and authorization method from API publishing function. In case that the AEF updates its authentication and authorization method and API invoker uses the old authentication and authorization method to invoke the service API, the AEF shall send a failure response to the API invoker with an indicator that indicates the authentication and authorization method used by the API invoker is incorrect. The API invoker shall contact the CAPIF core function to get the updated authentication and authorization method. Then the API invoker shall invoke the service API using the updated authentication and authorization method.
6.8 Security procedure for API invoker offboarding p. 18
Pre-conditions:
Step 1.
The API invoker has been onboarded successfully.
Step 0.
TLS session is established successfully between the CAPIF core function and the API invoker.
Step 1.
An event occurs within the API invoker to trigger the offboarding action.
Step 2.
The API invoker shall send Offboard API invoker request message to the CAPIF core function, including the CAPIF core function specific API invoker ID which was assigned by the CAPIF core function during the onboarding procedure.
Step 3.
The CAPIF core function shall verify the API invoker ID received in step 2 and check that the corresponding profile exists for this API invoker. With successful verification of the API invoker ID and its profile, the CAPIF core function shall cancel the enrolment of the API invoker and delete the API invoker profile. This includes deletion of API invoker certificate, service API authentication and authorization information, and onboard secret (if applicable). Depending on the operator policy, the CAPIF core function may retain the information of the offboarded API invoker.
Step 4.
The CAPIF core function sends Offboard API invoker response message, indicating the successful offboarding of the API invoker.
Step 5.
The API invoker shall delete the information, such as API invoker ID, Service API authentication / authorization information, API invoker certificate, Onboard_Secret (if applicable).
Step 6.
The CAPIF core function shall tear down the TLS session with the API invoker.
Step 7.
The CAPIF core function shall send Event notification message to the API exposing function to indicate that this API invoker is no longer valid.
Step 8.
The API exposing function shall delete the security related information associated with this API invoker depending on the method that was used previously to authenticate the API invoker, e.g. AEF PSK (TLS-PSK method as described in subclause 6.5.2.1), root certificate to validate the API invoker certificate (PKI method as described in subclause 6.5.2.2), access token (OAuth 2.0 method as described in subclause 6.5.2.3 of the present document, respectively).
Step 9.
The API exposing function shall tear down the TLS connection with the API invoker.
Step 10.
The API exposing function shall return Event notification acknowledge message to indicate that the security related information associated with this API invoker is successfully deleted and thus the API invoker no longer an acknowledged user.
6.9 Security procedures for CAPIF-7/7e reference points |R16| p. 20
To ensure security of the interfaces between API Exposing functions (Topology hiding entities and destination AEF handling service APIs), namely CAPIF-7 and CAPIF-7e:
- Security procedures as specified in clause 6.4 of this specification for CAPIF-2 reference point shall be used for secure communication, authentication and authorization, between the AEFs belonging to same trust domain over CAPIF-7 reference point.
- Security procedures as specified in the clause 6.5 of this specification for CAPIF-2e reference point shall be used for secure communication, authentication and authorization, between the AEFs belonging to different trust domains over CAPIF-7e reference point.
6.10 Security procedures for CAPIF-3e/4e/5e reference points |R16| p. 20
To ensure security of the interfaces between CAPIF entities between different trusted domains (CCF domain and API Provider Domain), namely CAPIF-3e, CAPIF-4e, and CAPIF-5e:
- 3GPP TS 33.210 shall be applied to secure messages on the reference points specified otherwise; and
- 3GPP TS 33.310 may be applied regarding the use of certificates with the security mechanisms of TS 33.210 unless otherwise specified in the present document.
