Update documentation - adding security information

Issue-ID: NONRTRIC-862
Signed-off-by: ychacon <yennifer.chacon@est.tech>
Change-Id: I5a9213e36faa4f2cf18dda9a5385c346df48fa1a

diff --git a/capifcore/README.md b/capifcore/README.md
index 1f70c6e..b4149f9 100644 (file)
--- a/capifcore/README.md
+++ b/capifcore/README.md
@@ -68,6 +68,14 @@ For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependenc
    has already been replaced in "TS29222_CAPIF_Discover_Service_API".
 3. If it has not been replaced, add a replacement above the "<new_replacement>" tag by copying and adapting the two rows above the tag.
 
+### Security in CAPIF
+
+Security requirements that are applicable to all CAPIF entities includes provide authorization mechanism for service APIs from the 3rd party API providers and support a common security mechanism for all API implementations to provide confidentiality and integrity protection.
+
+In the current implementation Keycloak is being used as identity and access management (IAM) solution that provides authentication, authorization, and user management for applications and services. Keycloak provides robust authentication mechanisms, including username/password, two-factor authentication, and client certificate authentication that complies with CAPIF security requirements.
+
+A docker-compose file is included to start up keycloak.
+
 ## Build and test
 
 To generate mocks manually, run the following command:
@@ -96,4 +104,8 @@ To run the Core Function from the command line, run the following commands from
 
     ./capifcore [-port <port (default 8090)>] [-secPort <Secure port (default 4433)>] [-chartMuseumUrl <URL to ChartMuseum>] [-repoName <Helm repo name (default capifcore)>] [-loglevel <log level (default Info)>] [-certPath <Path to certificate>] [-keyPath <Path to private key>]
 
+Use docker compose file to start Keycloak:
+
+    docker-compose up
+
 To run CAPIF Core as a K8s pod together with ChartMuseum, start and stop scripts are provided. The pod configurations are provided in the `configs` folder. CAPIF Core is then available on port `31570`.

diff --git a/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml b/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml
index 7b00bd2..eb013c1 100644 (file)
--- a/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml
+++ b/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml
@@ -15,7 +15,7 @@ participant eventservice
 participant loggingservice
 end box
 
-alt Regtister Consumer rApp
+alt Register Consumer rApp
     rAppCatalogue->rAppManager: Register consumer \nrApp
     alt#coral #coral Register Invoker
         rAppManager->capifcore: Register invoker with\n APIInvokerEnrolmentDetails
@@ -34,7 +34,7 @@ alt Regtister Consumer rApp
         eventservice->capp: subscriptionId
     end
 end
-alt Regtister provider rApp
+alt Register provider rApp
     rAppCatalogue->rAppManager: Register rApp, with\n rApp descriptor\n specifying which\n services to expose
     alt#paleGreen #paleGreen Provider Enrolment
         rAppManager->capifcore: Register provider with\n APIProviderEnrolmentDetails

diff --git a/docs/images/Onboardingnewinvoker.svg b/docs/images/Onboardingnewinvoker.svg
new file mode 100644 (file)
index 0000000..f7e5b13
--- /dev/null
+++ b/docs/images/Onboardingnewinvoker.svg
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="700px" preserveAspectRatio="none" style="width:996px;height:700px;background:#FFFFFF;" version="1.1" viewBox="0 0 996 700" width="996px" zoomAndPan="magnify"><defs/><g><rect fill="#DDDDDD" height="688.1172" style="stroke:#181818;stroke-width:0.5;" width="610" x="239" y="6"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="82" x="503" y="18.0669">CAPIF Core</text><rect fill="#98FB98" height="499.5234" style="stroke:#000000;stroke-width:1.5;" width="980" x="10" y="98.2969"/><rect fill="#FA8072" height="132.6641" style="stroke:#000000;stroke-width:1.5;" width="928" x="20" y="458.1563"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="77" x2="77" y1="81.2969" y2="614.8203"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="281" x2="281" y1="81.2969" y2="614.8203"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="513" x2="513" y1="81.2969" y2="614.8203"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="676" x2="676" y1="81.2969" y2="614.8203"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="794" x2="794" y1="81.2969" y2="614.8203"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="943" x2="943" y1="81.2969" y2="614.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="89" x="30" y="77.9951">InvokerClient</text><ellipse cx="77.5" cy="13.5" fill="#E2E2F0" rx="8" ry="8" style="stroke:#181818;stroke-width:0.5;"/><path d="M77.5,21.5 L77.5,48.5 M64.5,29.5 L90.5,29.5 M77.5,48.5 L64.5,63.5 M77.5,48.5 L90.5,63.5 " fill="none" style="stroke:#181818;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="89" x="30" y="626.8154">InvokerClient</text><ellipse cx="77.5" cy="638.6172" fill="#E2E2F0" rx="8" ry="8" style="stroke:#181818;stroke-width:0.5;"/><path d="M77.5,646.6172 L77.5,673.6172 M64.5,654.6172 L90.5,654.6172 M77.5,673.6172 L64.5,688.6172 M77.5,673.6172 L90.5,688.6172 " fill="none" style="stroke:#181818;stroke-width:0.5;"/><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="77" x="243" y="50"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="63" x="250" y="69.9951">capifcore</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="77" x="243" y="613.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="63" x="250" y="633.8154">capifcore</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="113" x="457" y="50"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="99" x="464" y="69.9951">invokerservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="113" x="457" y="613.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="99" x="464" y="633.8154">invokerservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="113" x="620" y="50"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="99" x="627" y="69.9951">publishservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="113" x="620" y="613.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="99" x="627" y="633.8154">publishservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="102" x="743" y="50"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="88" x="750" y="69.9951">eventservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="102" x="743" y="613.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="88" x="750" y="633.8154">eventservice</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="74" x="906" y="50"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="60" x="913" y="69.9951">keycloak</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="74" x="906" y="613.8203"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="60" x="913" y="633.8154">keycloak</text><path d="M10,98.2969 L74,98.2969 L74,105.4297 L64,115.4297 L10,115.4297 L10,98.2969 " fill="#98FB98" style="stroke:#000000;stroke-width:1.5;"/><rect fill="none" height="499.5234" style="stroke:#000000;stroke-width:1.5;" width="980" x="10" y="98.2969"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="19" x="25" y="111.3638">alt</text><text fill="#000000" font-family="sans-serif" font-size="11" font-weight="bold" lengthAdjust="spacing" textLength="116" x="89" y="110.5073">[Onboard Invoker]</text><polygon fill="#181818" points="269.5,147.6953,279.5,151.6953,269.5,155.6953,273.5,151.6953" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="77.5" x2="275.5" y1="151.6953" y2="151.6953"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="131" x="84.5" y="131.4966">Register invoker with</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="176" x="88.5" y="146.6294">APIInvokerEnrolmentDetails</text><polygon fill="#181818" points="501.5,176.8281,511.5,180.8281,501.5,184.8281,505.5,180.8281" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="281.5" x2="507.5" y1="180.8281" y2="180.8281"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="208" x="288.5" y="175.7622">Creates a new API Invoker profile</text><line style="stroke:#181818;stroke-width:1.0;" x1="513.5" x2="555.5" y1="209.9609" y2="209.9609"/><line style="stroke:#181818;stroke-width:1.0;" x1="555.5" x2="555.5" y1="209.9609" y2="222.9609"/><line style="stroke:#181818;stroke-width:1.0;" x1="514.5" x2="555.5" y1="222.9609" y2="222.9609"/><polygon fill="#181818" points="524.5,218.9609,514.5,222.9609,524.5,226.9609,520.5,222.9609" style="stroke:#181818;stroke-width:1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="123" x="520.5" y="204.895">Create apiInvokerId</text><polygon fill="#181818" points="931,263.2266,941,267.2266,931,271.2266,935,267.2266" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="513.5" x2="937" y1="267.2266" y2="267.2266"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="143" x="520.5" y="247.0278">Register client and get</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="114" x="524.5" y="262.1606">onboardingSecret</text><polygon fill="#181818" points="524.5,292.3594,514.5,296.3594,524.5,300.3594,520.5,296.3594" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="518.5" x2="942" y1="296.3594" y2="296.3594"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="114" x="530.5" y="291.2935">onboardingSecret</text><polygon fill="#181818" points="664.5,321.4922,674.5,325.4922,664.5,329.4922,668.5,325.4922" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="513.5" x2="670.5" y1="325.4922" y2="325.4922"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="139" x="520.5" y="320.4263">Get available services</text><polygon fill="#181818" points="524.5,350.625,514.5,354.625,524.5,358.625,520.5,354.625" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="518.5" x2="675.5" y1="354.625" y2="354.625"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="113" x="530.5" y="349.5591">Available services</text><polygon fill="#181818" points="292.5,394.8906,282.5,398.8906,292.5,402.8906,288.5,398.8906" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="286.5" x2="512.5" y1="398.8906" y2="398.8906"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="114" x="298.5" y="378.6919">Services available</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="92" x="302.5" y="393.8247">for the invoker</text><polygon fill="#181818" points="88.5,439.1563,78.5,443.1563,88.5,447.1563,84.5,443.1563" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="82.5" x2="280.5" y1="443.1563" y2="443.1563"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="136" x="94.5" y="422.9575">Invoker with invokerId</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="140" x="98.5" y="438.0903">and available services</text><path d="M20,458.1563 L84,458.1563 L84,465.2891 L74,475.2891 L20,475.2891 L20,458.1563 " fill="#FA8072" style="stroke:#000000;stroke-width:1.5;"/><rect fill="none" height="132.6641" style="stroke:#000000;stroke-width:1.5;" width="928" x="20" y="458.1563"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="19" x="35" y="471.2231">alt</text><text fill="#000000" font-family="sans-serif" font-size="11" font-weight="bold" lengthAdjust="spacing" textLength="208" x="99" y="470.3667">[Subscribe to publishing events]</text><polygon fill="#181818" points="782,507.5547,792,511.5547,782,515.5547,786,511.5547" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="77.5" x2="788" y1="511.5547" y2="511.5547"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="127" x="84.5" y="491.356">Subscribe to events</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="144" x="88.5" y="506.4888">with EventSubscription</text><line style="stroke:#181818;stroke-width:1.0;" x1="794" x2="836" y1="540.6875" y2="540.6875"/><line style="stroke:#181818;stroke-width:1.0;" x1="836" x2="836" y1="540.6875" y2="553.6875"/><line style="stroke:#181818;stroke-width:1.0;" x1="795" x2="836" y1="553.6875" y2="553.6875"/><polygon fill="#181818" points="805,549.6875,795,553.6875,805,557.6875,801,553.6875" style="stroke:#181818;stroke-width:1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="135" x="801" y="535.6216">Create subscriptionId</text><polygon fill="#181818" points="88.5,578.8203,78.5,582.8203,88.5,586.8203,84.5,582.8203" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="82.5" x2="793" y1="582.8203" y2="582.8203"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="88" x="94.5" y="577.7544">subscriptionId</text><!--MD5=[2a2162ad220229cd18e475b9115b1291]
+@startuml Onboarding new invoker\r
+actor InvokerClient\r
+\r
+box "CAPIF Core"\r
+participant capifcore\r
+participant invokerservice\r
+participant publishservice\r
+participant eventservice\r
+end box\r
+\r
+participant keycloak\r
+\r
+\r
+alt#PaleGreen #PaleGreen Onboard Invoker\r
+    InvokerClient->capifcore: Register invoker with\n APIInvokerEnrolmentDetails\r
+    capifcore->invokerservice: Creates a new API Invoker profile\r
+    invokerservice->invokerservice: Create apiInvokerId\r
+    invokerservice->keycloak: Register client and get\n onboardingSecret\r
+    keycloak->invokerservice: onboardingSecret\r
+    invokerservice->publishservice: Get available services\r
+    publishservice->invokerservice: Available services\r
+    invokerservice->capifcore: Services available\n for the invoker\r
+    capifcore->InvokerClient: Invoker with invokerId\n and available services\r
+    alt#Salmon #Salmon Subscribe to publishing events\r
+        InvokerClient->eventservice: Subscribe to events\n with EventSubscription\r
+        eventservice->eventservice: Create subscriptionId\r
+        eventservice->InvokerClient: subscriptionId\r
+    end\r
+end\r
+\r
+@enduml\r
+
+PlantUML version 1.2022.7(Mon Aug 22 19:01:30 CEST 2022)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: null
+--></g></svg>
\ No newline at end of file

diff --git a/docs/images/architectureCAPIF.png b/docs/images/architectureCAPIF.png
new file mode 100755 (executable)
index 0000000..a3fcc72
Binary files /dev/null and b/docs/images/architectureCAPIF.png differ

diff --git a/docs/images/securitymodel.png b/docs/images/securitymodel.png
new file mode 100644 (file)
index 0000000..997e000
Binary files /dev/null and b/docs/images/securitymodel.png differ

diff --git a/docs/overview.rst b/docs/overview.rst
index dd1cfc0..eb13450 100644 (file)
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -1,11 +1,186 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright (C) 2022 Nordix
+.. Copyright (C) 2023 Nordix
 
+#############
 Overview
-~~~~~~~~
+#############
 
 Within Service Management and Exposure the CAPIF Core product is developed. It resides in the "capifcore" folder.
 
-
 This product is a part of :doc:`NONRTRIC <nonrtric:index>`.
+
+*************
+CAPIF
+*************
+
+Introduction
+************
+
+CAPIF stands for Common API framework and it was developed by 3GPP to enable a unified Northbound API framework across 3GPP network functions, and to ensure that there is a single and harmonized approach for API development.
+
+Key features in capif includes onboarding and offloading of application functions, service discovery and management, event subscription and notification as well as authorization and authentication.
+
+It was delivered in Rel-15 (Refer to 3GPP TS 23.222 and 3GPP TS 29.222)
+
+Functional entities
+===================
+
+The CAPIF consists of an API provider functions, the CAPIF core functions and API Invoker.
+
+.. image:: ./images/architectureCAPIF.png
+   :width: 500pt
+   :alt: High level functional architecture for the CAPIF (3GPP TS 23.222).
+
+CAPIF Core function
+~~~~~~~~~~~~~~~~~~~
+
+The CAPIF core functions support the API invokers to access the service APIs. It consists of the following capabilities:
+
+* Authenticating the API invoker based on the identity and other information required for authentication of the API invoker;
+* Supporting mutual authentication with the API invoker;
+* Providing authorization for the API invoker prior to accessing the service API;
+* Publishing, storing and supporting the discovery of service APIs information;
+* Monitoring the service API invocations;
+* Onboarding a new API invoker and offboarding an API invoker;
+* Supports publishing, discovery of service APIs information with another CAPIF core function in CAPIF interconnection.
+
+API Invoker
+~~~~~~~~~~~
+
+The API invoker is the entity which invokes the CAPIF or service APIs, typically provided by a 3rd party application provider who has service agreement with PLMN operator.
+
+The API invoker supports the following capabilities:
+
+* Triggering API invoker onboarding/offboarding;
+* Supporting the authentication by providing the API invoker identity and other information required for authentication of the API invoker;
+* Supporting mutual authentication with CAPIF;
+* Obtaining the authorization prior to accessing the service API;
+* Discovering service APIs information; and
+* Invoking the service APIs.
+
+
+API Provider functions
+~~~~~~~~~~~~~~~~~~~~~~
+
+The API provider functions consists of:
+
+* **API exposing function** is the provider of the service APIs and is also the service communication entry point of the service API to the API invokers. Provides access control, logging, charging, provides authentication and authorization support.
+* **API publishing function** is responsible for the capability to publish the service API information of the API provider to the CAPIF core functions in order to enable the discovery of APIs by the API invoker.
+* **API management function** is the entity which registers and maintains registration information of the API provider domain functions on the CAPIF core function.
+
+CAPIF core function APIs
+************************
+
+* **CAPIF_Discover_Service_API** API: This API enables the API invoker to communicate with the CAPIF core function to discover the published service API information.
+* **CAPIF_Publish_Service_API** API:This API enables the API publishing function to communicate with the CAPIF core function to publish the service API information and manage the published service API information.
+* **CAPIF_Events** API: This API enables the API subscribing entity to communicate with the CAPIF core function to subscribe to and unsubscribe from CAPIF events and receive subsequent notification of CAPIF events. This API is used for the subscription to and notifications of those CAPIF events that are not bound to any of the other CAPIF core function APIs.
+* **CAPIF_API_invoker_management** API: This API enables the API invoker to communicate with the CAPIF core function to enroll as a registered user of CAPIF and manage the enrollment information.
+* **CAPIF_Security** API:This API enables the API invoker to communicate with the CAPIF core function to authenticate and obtain authorization to access service APIs.
+* **CAPIF_Monitoring** API: This API enables the API management function to communicate with the CAPIF core function to subscribe to and unsubscribe from CAPIF events related to monitoring and receive subsequent notification of CAPIF monitoring events.
+* **CAPIF_Logging_API_Invocation** API: This API enables the API exposing function to communicate with the CAPIF core function to log the information related to service API invocation.
+* **CAPIF_Auditing** API: This API enables the API management function to communicate with the CAPIF core function to retrieve the log information related to service API invocation.
+* **CAPIF_Access_Control_Policy** API: This API enables the API exposing function to obtain the policy to perform access control on the service API invocations.
+* **CAPIF_Routing_Info** API: This API enables the API exposing function to obtain the routing information to forward the API invocation to another API exposing function.
+* **CAPIF_API_provider_management** API: This API enables the API Management Function to communicate with the CAPIF core function to register the API provider domain functions as authorized users of the CAPIF functionalities.
+
+The table below lists the CAPIF Core Function APIs.
+
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|     **Service Name**              | **Service Operations**       | **Operation Semantics**                      | **Consumer(s)**                                                                        |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Discover_Service_API        | Discover_Service_API         | GET /allServiceAPIs                          | API Invoker, CAPIF core function                                                       |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Publish_Service_API         | Publish_Service_API          | POST /{apfId}/service-apis                   | API Publishing Function, CAPIF core function                                           |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Unpublish_Service_API        | DELETE /{apfId/service-apis/{serviceApiId}   | API Publishing Function, CAPIF core function                                           |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Update_Service_API           | PUT /{apfId/service-apis/{serviceApiId}      | API Publishing Function, CAPIF core function                                           |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Get_Service_API              | GET /{apfId}/service-apis                    | API Publishing Function, CAPIF core function                                           |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Events_API                  | Subscribe_Event              | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Notify_Event                 | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Unsubscribe_Event            | Subscribe/Notify                             | API Invoker, API Publishing Function, API Management Function, API Exposing Function   |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_API_Invoker_Management_API  | Onboard_API_Invoker          | POST /onboardedInvokers                      | API Invoker                                                                            |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Offboard_API_Invoker         | DELETE /onboardedInvokers/{onboardingId}     | API Invoker                                                                            |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Notify_Onboarding_Completion | Subscribe/Notify                             | API Invoker                                                                            |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Update_API_Invoker_Details   | PUT /onboardedInvokers/{onboardingId}        | API Invoker                                                                            |
+|                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Notify_Update_Completion     | Subscribe/Notify                             | API Invoker                                                                            |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Security_API                | Obtain_Security_Method       | PUT /trustedInvokers/{apiInvokerId}          | API Invoker                                                                            |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Obtain_Authorization         | POST /securities/{securityId}/token          | API Invoker                                                                            |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Obtain_API_Invoker_Info      | GET /trustedInvokers/{apiInvokerId}          | API exposing function                                                                  |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Revoke_Authorization         | DELETE /trustedInvokers/{apiInvokerId}       | API exposing function                                                                  |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_API_Provider_Management_API | Register_API_Provider        | POST /registrations                          | API Management Function                                                                |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Update_API_Provider          | PUT /registrations/{registrationId}          | API Management Function                                                                |
++                                   +------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+|                                   | Deregister_API_Provider      | DELETE /registrations/{registrationId}       | API Management Function                                                                |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Monitoring_API              | Event operations             |                                              | API Management Function                                                                |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Logging_API_Invocation_API  | Log_API_Invocation           | POST /{aefId}/logs                           | API exposing function                                                                  |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Auditing_API                | Query_API_Invocation_Log     | GET /apiInvocationLogs                       | API management function                                                                |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Access_Control_Policy_API   | Obtain_Access_Control_Policy | GET /accessControlPolicyList/{serviceApiId}  | API Exposing Function                                                                  |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+| CAPIF_Routing_Info_API            | Obtain_Routing_Info          | GET /service-apis/{serviceApiId}             | API exposing function                                                                  |
++-----------------------------------+------------------------------+----------------------------------------------+----------------------------------------------------------------------------------------+
+
+Security in CAPIF
+*****************
+
+CAPIF establish security requeriments for all the interfaces defined in the specification. There are also security requeriments that are applicable to all CAPIF entities, such as:
+
+- CAPIF shall provide mechanisms to hide the topology of the PLMN trust domain from the API invokers accessing the service APIs from outside the PLMN trust domain.
+- CAPIF shall provide mechanisms to hide the topology of the 3rd party API provider trust domain from the API invokers accessing the service APIs from outside the 3rd party API provider trust domain.
+- CAPIF shall provide authorization mechanism for service APIs from the 3rd party API providers.
+- CAPIF shall support a common security mechanism for all API implementations to provide confidentiality and integrity protection.
+
+The image below shows the functional security model for CAPIF architecture. CAPIF-1, CAPIF-2, CAPIF-3, CAPIF-4, CAPIF-5 and CAPIF-7 are interfaces that lie within the PLMN trust domain while the CAPIF-1e , CAPIF-2e, CAPIF-3e, CAPIF-4e, CAPIF-5e and CAPIF-7e interfaces are CAPIF core and AEF access points for API Invokers outside of the PLMN trust domain.
+
+.. image:: ./images/securitymodel.png
+   :width: 500pt
+   :alt: CAPIF functional security model (3GPP TS 33.122).
+
+Authentication and authorization are required for both API invokers that lie within the PLMN trust domain and API invokers that lie outside of the PLMN trust domain. For an API invoker that is outside of the PLMN trust domain, the CAPIF core function in coordination with the API exposing function utilizes the CAPIF-1e, CAPIF-2e and the CAPIF-3 interfaces to onboard, authenticate and authorize the API invoker prior to granting access to CAPIF services.
+
+Security procedures for API invoker onboarding
+==============================================
+
+The API invoker and the CAPIF core function shall establish a secure session.
+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.
+
+.. image:: ./images/Onboardingnewinvoker.svg
+   :alt: Procedure for API invoker onboarding
+
+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, API invoker's certificate and the API invoker Onboard_Secret (generated by the CAPIF core function provided by keycloak).
+
+Security method negotiation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+As a pre-condition the API invoker must be onboarded with the CAPIF core function.
+
+After successful mutual authentication on CAPIF-1e interface, 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 it supports for each AEF.
+
+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 sent by the API invoker and send a Security Method Response message to the API invoker indicating the selected security method for each AEF.
+
+API discovery
+~~~~~~~~~~~~~
+
+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.
\ No newline at end of file

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 91942e3..e6ae03c 100644 (file)
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -7,4 +7,5 @@ six
 sphinx_rtd_theme
 sphinxcontrib-needs
 sphinx_bootstrap_theme
-lfdocs-conf
\ No newline at end of file
+lfdocs-conf
+urllib3~=1.26.15
\ No newline at end of file