Fix documentation1.0.1

Issue-ID: AAF-1091
Signed-off-by: Aleksandra Maciaga <aleksandra.maciaga@nokia.com>
Change-Id: I057f20fa82057affae18dbaae5c0f4d0b979bde5

11 files changed, 128 insertions, 79 deletions

diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
index 1a5b3687..9166aa39 100644
--- a/docs/sections/architecture.rst
+++ b/docs/sections/architecture.rst
@@ -14,6 +14,14 @@ Interaction between components
    :height: 223px
    :alt: Interaction between components
 
+The micro-service called CertService is designed for requesting certificates signed by external Certificate Authority (CA) using CMP over HTTP protocol. It uses CMPv2 client to send and receive CMPv2 messages.
+
+CertService's client is also provided so other ONAP components (aka end components) can easily get certificate from CertService. End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server to protect external traffic and uses CertService's client to get it.
+
+CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
+
+To proof that CertService works Open Source CMPv2 server (EJBCA) is deployed and used in E2E tests.
+
 
 Simplified certificate enrollment flow
 --------------------------------------
@@ -22,8 +30,3 @@ Simplified certificate enrollment flow
    :width: 1191px
    :height: 893px
    :alt: Simplified certificate enrollment flow
-
-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
diff --git a/docs/sections/build.rst b/docs/sections/build.rst
index d533e330..44c38c46 100644
--- a/docs/sections/build.rst
+++ b/docs/sections/build.rst
@@ -3,7 +3,7 @@
 .. Copyright 2020 NOKIA
 
 Build
-=====
+======
 
 Jenkins
 -------
@@ -37,7 +37,7 @@ How to build images?
 --------------------
 
 #. Checkout the project from https://gerrit.onap.org/r/#/admin/projects/aaf/certservice
-#. Read information's stored in README.md file
+#. Read information stored in README.md file
 #. Use a Makefile to build images::
 
     make build
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
index 43de0e43..b325712e 100644
--- a/docs/sections/configuration.rst
+++ b/docs/sections/configuration.rst
@@ -3,7 +3,7 @@
 .. Copyright 2020 NOKIA
 
 Configuration
-=============
+==============
 
 
 Configuring Cert Service
@@ -41,7 +41,7 @@ Example cmpServers.json file:
 
 This contains list of CMP Servers, where each server has following properties:
 
-    - *caName* - name of the external CA server. It's used to match *CA_NAME* sent by client in order to match proper configuration.
+    - *caName* - name of the external CA server. It's used to match *CA_NAME* sent by CertService client in order to match proper configuration.
     - *url* - URL to CMPv2 server
     - *issuerDN* - Distinguished Name of the CA that will sign the certificate
     - *caMode* - Issuer mode. Allowed values are *CLIENT* and *RA*
@@ -57,8 +57,8 @@ This configuration is read on the application start. It can also be reloaded in
 Next sections explain how to configure Cert Service in local (docker-compose) and OOM Deployments.
 
 
-Configuring in local(docker-compose) deployment:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring in local (docker-compose) deployment:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Before application start:
 """""""""""""""""""""""""
@@ -76,6 +76,9 @@ When application is running:
 
     docker exec -it <certservice-container-name> bash
 
+    e.g.
+    docker exec -it aafcert-service bash
+
 3. Edit *cmpServers.json* file::
 
     vim /etc/onap/aaf/certservice/cmpServers.json
@@ -83,7 +86,7 @@ When application is running:
 4. Save the file. Note that this file is mounted as volume, so change will be persistent.
 5. Reload configuration::
 
-    curl -I https://localhost:8443/reload --cacert /etc/onap/aaf/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/aaf/certservice/certs/certServiceServer-keystore.p12 --pass secret
+    curl -I https://localhost:8443/reload --cacert /etc/onap/aaf/certservice/certs/root.crt --cert-type p12 --cert /etc/onap/aaf/certservice/certs/certServiceServer-keystore.p12 --pass $KEYSTORE_PASSWORD
 
 6. Exit container::
 
@@ -96,7 +99,7 @@ Configuring in OOM deployment:
 Before OOM installation:
 """"""""""""""""""""""""
 
-Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking aaf Charts.
+Note! This must be executed before calling *make all* (from OOM Installation) or needs remaking AAF charts.
 
 
 1. Edit *cmpServers.json* file. If OOM *global.addTestingComponents* flag is set to:
@@ -109,15 +112,20 @@ Note! This must be executed before calling *make all* (from OOM Installation) or
 When CertService is deployed:
 """""""""""""""""""""""""""""
 
-1. Encode your configuration to base64::
+1. Create file with configuration
+
+2. Encode your configuration to base64::
 
-    echo "CONFIGURATION_TO_ENCODE" | base64
+    cat <configuration_file> | base64
 
-2. Edit secret::
+3. Edit secret::
 
-    kubectl edit secret <cmp-servers-secret-name> # aaf-cert-service-secret by default
+    kubectl -n onap edit secret <cmp-servers-secret-name>
 
-3. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
+    e.g.
+    kubectl -n onap edit secret aaf-cert-service-secret
+
+4. Replace value for *cmpServers.json* with your base64 encoded configuration. For example:
 
   .. code-block:: yaml
 
@@ -134,17 +142,20 @@ When CertService is deployed:
           uid: 6a037526-83ed-11ea-b731-fa163e2144f6
         type: Opaque
 
-4. Save and exit
-5. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
-6. To reload configuration enter CertService pod::
+5. Save and exit
+6. New configuration will be automatically mounted to CertService pod, but application configuration reload is needed.
+7. To reload configuration enter CertService pod::
+
+    kubectl -n onap exec -it <cert-service-pod-name> bash
 
-    kubectl exec -it <cert-service-pod-name> bash
+    e.g.
+    kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
 
-7. Reload configuration::
+8. Reload configuration::
 
     curl -I https://localhost:$HTTPS_PORT/reload --cacert $ROOT_CERT --cert-type p12 --cert $KEYSTORE_P12_PATH --pass $KEYSTORE_PASSWORD
 
-8. Exit container::
+9. Exit container::
 
     exit
 
@@ -185,19 +196,19 @@ This section describes how to use custom, external certificates for CertService
 1. Set *tls.certificateExternalSecret* flag to true in *kubernetes/aaf/charts/aaf-cert-service/values.yaml*
 2. Prepare secret for CertService. It must be provided before OOM installation. It must contain four files:
 
-    - *certServiceServer-keystore.jks*  - keystore in jks format. Signed by some Root CA
-    - *certServiceServer-keystore.p12* - same keystore in p12 format
-    - *truststore.jks* - truststore in jks format, containing certificates of the Root CA that signed CertService Client certificate
-    - *root.crt* - certificate of the RootCA that signed Client certificate in crt format
+    - *certServiceServer-keystore.jks*  - keystore in JKS format. Signed by some Root CA
+    - *certServiceServer-keystore.p12* - same keystore in PKCS#12 format
+    - *truststore.jks* - truststore in JKS format, containing certificates of the Root CA that signed CertService Client certificate
+    - *root.crt* - certificate of the RootCA that signed Client certificate in CRT format
 
 3. Name the secret properly - the name should match *tls.server.secret.name* value from *kubernetes/aaf/charts/aaf-cert-service/values.yaml* file
 
 4. Prepare secret for CertService Client. It must be provided before OOM installation. It must contain two files:
 
-    - *certServiceClient-keystore.jks*  - keystore in jks format. Signed by some Root CA
-    - *truststore.jks* - truststore in jks format, containing certificates of the RootCA that signed CertService certificate
+    - *certServiceClient-keystore.jks*  - keystore in JKS format. Signed by some Root CA
+    - *truststore.jks* - truststore in JKS format, containing certificates of the RootCA that signed CertService certificate
 
-5. Name the secret properly - the name should match *global.aaf.certService.client.secret.name*
+5. Name the secret properly - the name should match *global.aaf.certService.client.secret.name* value from *kubernetes/onap/values.yaml* file
 
 6. Provide keystore and truststore passwords for CertService. It can be done in two ways:
 
diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
index 8ef137fc..510bd811 100644
--- a/docs/sections/installation.rst
+++ b/docs/sections/installation.rst
@@ -3,7 +3,7 @@
 .. Copyright 2020 NOKIA
 
 Installation
-============
+=============
 
 .. note::
    * This section is used to describe how a software component is acquired and installed.
diff --git a/docs/sections/introduction.rst b/docs/sections/introduction.rst
index 0b7e8d1b..9d6c7816 100644
--- a/docs/sections/introduction.rst
+++ b/docs/sections/introduction.rst
@@ -5,19 +5,12 @@
 
 
 Introduction
-============
+=============
 
 Overview
 --------
-The micro-service called CertService is designed for requesting certificates signed by external Certificate Authority (CA) using CMP over HTTP protocol. It uses CMPv2 client to send and receive CMPv2 messages.
 
-CertService's client is also provided so other ONAP components (aka end components) can easily get certificate from CertService. End component is an ONAP component (e.g. DCAE collector or controller) which requires certificate from CMPv2 server to protect external traffic and uses CertService's client to get it.
-
-CertService's client communicates with CertService via REST API over HTTPS, while CertService with CMPv2 server via CMP over HTTP.
-
-To proof that CertService works Open Source CMPv2 server (EJBCA) is deployed and used in E2E tests.
-
-It is planned that Network Functions (aka xNFs) will get certificates from the same CMPv2 server and the same CA hierarchy, but will use own means to get such certificates. Cause xNFs and ONAP will get certificates signed by the same root CA and will trust such root CA, both parties will automatically trust each other and can communicate with each other.
+In Frankfurt release AAF was enhanced by Certificate Management Protocol ver. 2 (CMPv2) support. Such support is handled by new AAF's microservice called CertService. CertService provides certificates signed by external CMPv2 server - further on such certificates are called operators certificates. Operators certificates are meant to secure external ONAP traffic - traffic between network functions (xNFs) and ONAP.
 
 
 Context View
@@ -28,6 +21,18 @@ Context View
    :height: 315px
    :alt: CMPV2 Context View
 
+It is planned that Network Functions (aka xNFs) will get certificates from the same CMPv2 server and the same CA hierarchy, but will use own means to get such certificates. Cause xNFs and ONAP will get certificates signed by the same root CA and will trust such root CA, both parties will automatically trust each other and can communicate with each other.
+
+
+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>`_.
+
+
+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
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
index abf951f1..65d08108 100644
--- a/docs/sections/logging.rst
+++ b/docs/sections/logging.rst
@@ -2,30 +2,35 @@
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright 2020 NOKIA
 
-.. _cert_logs:
 
 Logging
 =======
 
-Certification Service API 
---------------------------
-To see console Certification Service logs use:
+CertService API
+---------------
+To see CertService console logs use:
 
 - Docker:
 
 .. code-block:: bash
 
-   docker logs <cert-service-container-name>
+    docker logs <cert-service-container-name>
+
+    e.g.
+    docker logs aafcert-service
 
 - Kubernetes:
 
 .. code-block:: bash
 
-   kubectl logs <cert-service-pod-name>
+    kubectl -n onap logs <cert-service-pod-name>
+
+    e.g.
+    kubectl -n onap logs $(kubectl -n onap get pods | grep cert-service | awk '{print $1}')
 
-Console logs contain logs for logging levels from **DEBUG** to **ERROR**.
+Console logs contains logs for logging levels from **DEBUG** to **ERROR**.
 
-Certification Service logs for different logging levels are available in the container:
+CertService logs for different logging levels are available in the container:
 
 - Docker:
 
@@ -33,11 +38,17 @@ Certification Service logs for different logging levels are available in the con
 
     docker exec -it <cert-service-container-name> bash
 
+    e.g.
+    docker exec -it aafcert-service bash
+
 - Kubernetes:
 
 .. code-block:: bash
 
-    kubectl exec -it <cert-service-pod-name> bash
+    kubectl -n onap exec -it <cert-service-pod-name> bash
+
+    e.g.
+    kubectl -n onap exec -it $(kubectl -n onap get pods | grep cert-service | awk '{print $1}') bash
 
 Path to logs:
 
@@ -51,30 +62,36 @@ Available log files:
 
 User cannot change logging levels.
 
+.. _cert_logs:
 
-
-Certification Service Client
-----------------------------
-To see console Certification Service Client logs use :
+CertService client
+------------------
+To see CertService client console logs use :
 
 - Docker: 
 
 .. code-block:: bash
    
-   docker logs <cert-service-client-container-name>
+    docker logs <cert-service-client-container-name>
+
+    e.g.
+    docker logs aafcert-client
 
 - Kubernetes: 
-  CertService Client is used as init container in other components. In the following example:
-    - *<some-component-pod-name>* refers to the component that uses CertService Client as init container
-    - *<cert-service-client-init-container-name>* refers to name of init container used by the mentioned component. It can be found by executing *'kubectl descrine pod <some-component-pod-name>'* and looking into 'Init Containers section'
+  CertService client is used as init container in other components. In the following example:
+    - *<some-component-pod-name>* refers to the component that uses CertService client as init container
+    - *<cert-service-client-init-container-name>* refers to name of init container used by the mentioned component. It can be found by executing *'kubectl -n onap descrine pod <some-component-pod-name>'* and looking into 'Init Containers section'
 
 .. code-block:: bash
 
-   kubectl logs <some-component-pod-name> -c <cert-service-client-init-container-name>
+    kubectl -n onap logs <some-component-pod-name> -c <cert-service-client-init-container-name>
+
+    e.g.
+    kubectl -n onap logs <some-component-pod-name> -c cert-service-client
 
 
 
-| Container stops after execution, so all logs available are printed to console.
+| Container stops after execution, so all available logs are printed on console.
 | User cannot change logging levels.
 
 Client application exits with following exit codes:
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
index d6ceac87..b757b3bd 100644
--- a/docs/sections/offeredapis.rst
+++ b/docs/sections/offeredapis.rst
@@ -4,7 +4,7 @@
 .. _offeredapis:
 
 Offered APIs
-============
+=============
 
 AAF Cert Service Api
 --------------------
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
index d01a84a8..a17829b8 100644
--- a/docs/sections/release-notes.rst
+++ b/docs/sections/release-notes.rst
@@ -4,7 +4,7 @@
 
 
 Release Notes
-=============
+==============
 
 Version: 1.0.1
 --------------
diff --git a/docs/sections/resources/certService_cert_enrollment_flow.png b/docs/sections/resources/certService_cert_enrollment_flow.png
index 6e070bfe..87d15adc 100644
--- a/docs/sections/resources/certService_cert_enrollment_flow.png
+++ b/docs/sections/resources/certService_cert_enrollment_flow.png
diff --git a/docs/sections/troubleshooting.rst b/docs/sections/troubleshooting.rst
index 1d454ccf..192a9d6a 100644
--- a/docs/sections/troubleshooting.rst
+++ b/docs/sections/troubleshooting.rst
@@ -3,7 +3,7 @@
 .. Copyright 2020 NOKIA
 
 Troubleshooting
-===============
+================
 
 
 
diff --git a/docs/sections/usage.rst b/docs/sections/usage.rst
index e52c1447..0aacbe3d 100644
--- a/docs/sections/usage.rst
+++ b/docs/sections/usage.rst
@@ -3,22 +3,22 @@
 .. Copyright 2020 NOKIA
 
 How to use functionality
-========================
+=========================
 Common information to docker and Kubernetes modes described below
 
 Basic information
 -----------------
-Certification Service Client needs the following configuration parameters to work properly:
+CertService client needs the following configuration parameters to work properly:
 
-1. Parameters for connection to Certification Service API to obtain certificate and trust anchors
+1. Parameters for connection to CertService API to obtain certificate and trust anchors
   
-  - REQUEST_URL *(default: https://aaf-cert-service:8443/v1/certificate/)* - URL to Certification Service API
-  - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout In miliseconds for REST API calls
+  - REQUEST_URL *(default: https://aaf-cert-service:8443/v1/certificate/)* - URL to CertService API
+  - REQUEST_TIMEOUT *(default: 30000[ms])* - Timeout in milliseconds for REST API calls
   - OUTPUT_PATH *(required)* - Path where client will output generated certificate and trust anchor
   - CA_NAME *(required)* - Name of CA which will enroll certificate. Must be same as configured on server side. Used in REST API calls
 
 
-2. Parameters to generate CSR file:
+2. Parameters to generate Certificate Signing Request (CSR):
   
   - COMMON_NAME *(required)* - Common name for which certificate from CMPv2 server should be issued
   - ORGANIZATION *(required)* - Organization for which certificate from CMPv2 server should be issued
@@ -28,14 +28,14 @@ Certification Service Client needs the following configuration parameters to wor
   - COUNTRY *(required)* - Country for which certificate from CMPv2 server should be issued
   - SANS *(optional)(SANS's should be separated by a colon e.g. test.onap.org:onap.com)* - Subject Alternative Names (SANs) for which certificate from CMPv2 server should be issued.
 
-3. Parameters to establish secure communication:
+3. Parameters to establish secure communication to CertService:
 
   - KEYSTORE_PATH *(required)*
   - KEYSTORE_PASSWORD *(required)*
   - TRUSTSTORE_PATH *(required)*
   - TRUSTSTORE_PASSWORD *(required)*
 
-Certification Service Client image can be found on Nexus repository :
+CertService client image can be found on Nexus repository :
 
 .. code-block:: bash
 
@@ -44,19 +44,20 @@ Certification Service Client image can be found on Nexus repository :
 
 As standalone docker container
 ------------------------------
-You need certificate and trust anchors to connect to certification service API via HTTPS. Information how to generate truststore and keystore files you can find in project repository README `Gerrit GitWeb <https://gerrit.onap.org/r/gitweb?p=aaf%2Fcertservice.git;a=summary>`__
+You need certificate and trust anchors to connect to CertService API via HTTPS. Information how to generate truststore and keystore files you can find in project repository README `Gerrit GitWeb <https://gerrit.onap.org/r/gitweb?p=aaf%2Fcertservice.git;a=summary>`__
 
-To run Certification Service Client as standalone docker container execute following steps:
+To run CertService client as standalone docker container execute following steps:
 
 1. Create file '*$PWD/client.env*' with environments as in example below:
 
 .. code-block:: bash
 
   #Client envs
-  REQUEST_URL=<url to certification service API>
+  REQUEST_URL=<URL to CertService API>
   REQUEST_TIMEOUT=10000
   OUTPUT_PATH=/var/certs
   CA_NAME=RA
+
   #CSR config envs
   COMMON_NAME=onap.org
   ORGANIZATION=Linux-Foundation
@@ -65,9 +66,10 @@ To run Certification Service Client as standalone docker container execute follo
   STATE=California
   COUNTRY=US
   SANS=test.onap.org:onap.com
+
   #TLS config envs
   KEYSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-keystore.jks
-  KEYSTORE_PASSWORD=<password to keystore.jks>
+  KEYSTORE_PASSWORD=<password to certServiceClient-keystore.jks>
   TRUSTSTORE_PATH=/etc/onap/aaf/certservice/certs/certServiceClient-truststore.jks
   TRUSTSTORE_PASSWORD=<password to certServiceClient-truststore.jks>
 
@@ -81,13 +83,13 @@ To run Certification Service Client as standalone docker container execute follo
     --env-file <$PWD/client.env (same as in step1)> \
     --network <docker network of cert service> \
     --mount type=bind,src=<path to local host directory where certificate and trust anchor will be created>,dst=<OUTPUT_PATH (same as in step 1)> \
-    --volume <local path to keystore.jks>:<KEYSTORE_PATH> \
-    --volume <local path to trustore.jks>:<TRUSTSTORE_PATH> \
+    --volume <local path to keystore in JKS format>:<KEYSTORE_PATH> \
+    --volume <local path to truststore in JKS format>:<TRUSTSTORE_PATH> \
     nexus3.onap.org:10001/onap/org.onap.aaf.certservice.aaf-certservice-client:$VERSION
 
 
 
-After successful creation of certifications, container exits with exit code 0, expected logs looks like:
+After successful creation of certifications, container exits with exit code 0, expected log looks like:
 
 .. code-block:: bash
 
@@ -112,7 +114,18 @@ If container exits with non 0 exit code, you can find more information in logs,
 As init container for Kubernetes
 --------------------------------
 
-To run Certification Service Client as init container for ONAP component, add following configuration to deploymnet:
+In order to run CertService client as init container for ONAP component you need to:
+
+    - define an init container and use CerService Client image
+    - provide client configuration through ENV variables in the init container
+    - define two volumes:
+
+        - first for generated certificates - it will be mounted in the init container and in the component container
+        - second with secret containing keys and certificates for secure communication between CertService Client and CertService - it will be mounted only in the init container
+    - mount both volumes to the init container
+    - mount first volume to the component container
+
+You can use the following deployment example as a reference:
 
 .. code-block:: yaml