Content for TS 33.122 Word version: 18.4.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.3.1 Authentication and authorization
6.3.1.1 General
6.3.1.2 Security method negotiation
6.3.1.3 API discovery
6.3.1.4 Topology hiding
6.4 Security procedures for CAPIF-2 reference point
...
...
6 Security procedures p. 12
6.1 Security procedures for API invoker onboarding p. 12
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. 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.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. 13
6.3.1 Authentication and authorization p. 13
6.3.1.1 General p. 13
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. 14
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:
- The API invoker is onboarded with the CAPIF core function.
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. 14
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. 15
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. 15
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.
