Merge "Update RTD with certificate update use case"2.4.0

3 files changed, 159 insertions, 9 deletions

diff --git a/docs/sections/introduction.rst b/docs/sections/introduction.rst
index 023066b8..e46e207c 100644
--- a/docs/sections/introduction.rst
+++ b/docs/sections/introduction.rst
@@ -31,10 +31,12 @@ Functionality
 
 In Frankfurt release only `Initialization Request <https://tools.ietf.org/html/rfc4210#section-5.3.1>`_ with `ImplicitConfirm <https://tools.ietf.org/html/rfc4210#section-5.1.1.1>`_ is supported.
 
-Request sent to CMPv2 server is authenticated by secret value (initial authentication key) and reference value (used to identify the secret value) as described in `RFC-4210 <https://tools.ietf.org/html/rfc4210#section-4.2.1.2>`_.
+Istanbul release includes also support for `Key Update Request and Certification Request <https://tools.ietf.org/html/rfc4210#section-5.3.1>`_
 
+Initialization Request and Certification Request sent to CMPv2 server are authenticated by secret value (initial authentication key) and reference value (used to identify the secret value) as described in `RFC-4210 <https://tools.ietf.org/html/rfc4210#section-4.2.1.2>`_.
+Key Update Request uses `signature protection <https://datatracker.ietf.org/doc/html/rfc4210#section-5.1.3.3>`_ so old certificate and private key are needed to authenticate the request.
 
 Security considerations
 -----------------------
 
-CertService's REST API is protected by mutual HTTPS, meaning server requests client's certificate and **authenticate** only requests with trusted certificate. After ONAP default installation only certificate from CertService's client is trusted. **Authorization** isn't supported in Frankfurt release.
\ No newline at end of file
+CertService's REST API is protected by mutual HTTPS, meaning server requests client's certificate and **authenticate** only requests with trusted certificate. After ONAP default installation only certificate from CertService's client is trusted. **Authorization** isn't supported in Frankfurt release.
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
index 8b2536fc..7d418211 100644
--- a/docs/sections/release-notes.rst
+++ b/docs/sections/release-notes.rst
@@ -7,13 +7,132 @@
 OOM Certification Service Release Notes
 ***************************************
 
+.. contents::
+    :depth: 2
+..
+
+Version: 2.4.0 [not released yet]
+=================================
+
 Abstract
-========
+--------
+
+This document provides the release notes for the Istanbul release.
+
+Summary
+-------
+
+Certificate update use case is now available. For details go to:
+:ref:`How to use instructions<how_to_use_certificate_update>`
+
+Release Data
+------------
+
++--------------------------------------+---------------------------------------------------------------------------------------+
+| **Project**                          | OOM                                                                                   |
+|                                      |                                                                                       |
++--------------------------------------+---------------------------------------------------------------------------------------+
+| **Docker images**                    |  * onap/org.onap.oom.platform.cert-service.oom-certservice-api:2.4.0                  |
+|                                      |  * onap/org.onap.oom.platform.cert-service.oom-certservice-post-processor:2.4.0       |
+|                                      |  * onap/org.onap.oom.platform.cert-service.oom-certservice-k8s-external-provider:2.4.0|
+|                                      |                                                                                       |
++--------------------------------------+---------------------------------------------------------------------------------------+
+| **Release designation**              | Istanbul                                                                              |
+|                                      |                                                                                       |
++--------------------------------------+---------------------------------------------------------------------------------------+
+
+
+New features
+------------
+
+- `OOM-2754 <https://jira.onap.org/browse/OOM-2754>`_ Implement certificate update in CMPv2 external issuer
+
+- `OOM-2753 <https://jira.onap.org/browse/OOM-2753>`_ Implement certificate update in CMPv2 CertService
+
+- `OOM-2744 <https://jira.onap.org/browse/OOM-2744>`_ Remove CertService Client mechanism from ONAP
+
+- `OOM-2649 <https://jira.onap.org/browse/OOM-2649>`_ Update contrib/ejbca to 7.x
+
+**Bug fixes**
+
+- `OOM-2771 <https://jira.onap.org/browse/OOM-2771>`_ Fix CertificateRequest resource was not found issue in CMPv2 external issuer
+
+- `OOM-2764 <https://jira.onap.org/browse/OOM-2764>`_ Fix sonar issues in CertService
+
+**Known Issues**
+
+None
+
+Deliverables
+------------
+
+Software Deliverables
+~~~~~~~~~~~~~~~~~~~~~
+Docker images mentioned in Release Date section.
+
+Documentation Deliverables
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :ref:`CMPv2 certificate provider description <cmpv2_cert_provider>`
+
+Known Limitations, Issues and Workarounds
+-----------------------------------------
+
+System Limitations
+~~~~~~~~~~~~~~~~~~
+
+Any known system limitations.
+
+
+Known Vulnerabilities
+~~~~~~~~~~~~~~~~~~~~~
+
+Any known vulnerabilities.
+
+
+Workarounds
+~~~~~~~~~~~
+
+Any known workarounds.
+
+
+Security Notes
+--------------
+
+**Fixed Security Issues**
+
+None
+
+**Known Security Issues**
+
+None
+
+
+Test Results
+------------
+Not applicable
+
+
+References
+----------
+
+For more information on the ONAP Istanbul release, please see:
+
+#. `ONAP Home Page`_
+#. `ONAP Documentation`_
+#. `ONAP Release Downloads`_
+#. `ONAP Wiki Page`_
+
+Version: 2.3.3
+==============
+
+Abstract
+--------
 
 This document provides the release notes for the Honolulu release.
 
 Summary
-=======
+-------
 
 Certification Service provides certificates signed by external CMPv2 server - such certificates are further called operators certificates. Operators certificates are meant to secure external ONAP traffic - traffic between network functions (xNFs) and ONAP.
 
@@ -21,7 +140,7 @@ This project was moved from Application Authorization Framework (AAF), to check
 
 
 Release Data
-============
+------------
 
 +--------------------------------------+---------------------------------------------------------------------------------------+
 | **Project**                          | OOM                                                                                   |
@@ -72,10 +191,10 @@ Docker images mentioned in Release Date section.
 Documentation Deliverables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- :doc:`CMPv2 certificate provider description <cmpv2-cert-provider>`
+- :ref:`CMPv2 certificate provider description <cmpv2_cert_provider>`
 
 Known Limitations, Issues and Workarounds
-=========================================
+-----------------------------------------
 
 System Limitations
 ------------------
@@ -108,12 +227,12 @@ None
 
 
 Test Results
-============
+------------
 Not applicable
 
 
 References
-==========
+----------
 
 For more information on the ONAP Honolulu release, please see:
 
diff --git a/docs/sections/usage.rst b/docs/sections/usage.rst
index 3031f364..cd48b55a 100644
--- a/docs/sections/usage.rst
+++ b/docs/sections/usage.rst
@@ -2,6 +2,8 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2020-2021 NOKIA
 
+.. _cmpv2_cert_provider:
+
 How to use functionality
 =========================
 Common information how to use CMPv2 certificate provider described below
@@ -38,6 +40,7 @@ Here is a definition of a *CMPv2Issuer* provided with ONAP installation:
     url: https://oom-cert-service:8443
     healthEndpoint: actuator/health
     certEndpoint: v1/certificate
+    updateEndpoint: v1/certificate-update
     caName: RA
     certSecretRef:
       name: cmpv2-issuer-secret
@@ -146,3 +149,29 @@ Here is an example of generated *secret* containing certificates:
     keystore.jks:    3786 bytes  <-- Certificate and Private Key (JKS)
     keystore.p12:    4047 bytes  <-- Certificate and Private Key (P12)
 
+.. _how_to_use_certificate_update:
+
+Certificate update
+------------------------------
+
+When the certificate already exists, but its date has expired or certificate data should be changed, then the certificate update scenario can be executed.
+This use case requires the update endpoint configured for *CMPv2Issuer* CRD:
+
+.. code-block:: yaml
+
+  ...
+  certEndpoint: v1/certificate
+  updateEndpoint: v1/certificate-update
+  caName: RA
+  ...
+
+If *updateEndpoint* field is not present or empty, then *certEndpoint* will be used (regular initial request instead of update) to get the certificate and this event will be logged.
+This behavior comes from releases prior to 2.4.0, when the certificate update feature was not implemented. To be able to perform the certificate update scenario,
+make sure the updateEndpoint is present in *CMPv2Issuer* CRD.
+
+There are two possible types of requests when a certificate needs to be updated: Key Update Request (KUR) and Certification Request (CR).
+Certification Service internally compares the old and new certificates fields. When they are equal, KUR request is sent.
+If there is a difference, the type of request is CR.
+
+There is a difference between CR and KUR in terms of the request authentication. Certificate Request uses IAK/RV mechanism, while KUR uses signature protection.
+The old certificate and the old private key are required to be sent in the headers of the update request.