Documentation update

- document prh authN/authZ feature
- broken linkage corrections
- wrong formatting corrections

Change-Id: Ie9bb86445712185ac4b9aebdbca75c629327d6fa
Issue-ID: DCAEGEN2-960
Signed-off-by: Tomek Kaminski <tomasz.kaminski@nokia.com>

6 files changed, 169 insertions, 91 deletions

diff --git a/docs/sections/apis/PRH.rst b/docs/sections/apis/PRH.rst
index f693ef76..2a7d0eae 100644
--- a/docs/sections/apis/PRH.rst
+++ b/docs/sections/apis/PRH.rst
@@ -1,3 +1,5 @@
+.. _prh_api:
+
 ==============================
 PRH (PNF Registration Handler)
 ==============================
@@ -28,7 +30,7 @@ Paths
 =====
 
 GET /events/unauthenticated.VES_PNFREG_OUTPUT
------------------------------------------------
+---------------------------------------------
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/sections/services/prh/architecture.rst b/docs/sections/services/prh/architecture.rst
index c47772a3..090c405e 100644
--- a/docs/sections/services/prh/architecture.rst
+++ b/docs/sections/services/prh/architecture.rst
@@ -2,13 +2,13 @@
 .. http://creativecommons.org/licenses/by/4.0
 
 PRH Architecture
-===================
+================
 
 **PRH** is a new DCAE micro-service which participates in the Physical Network Function Plug and Play (PNF PnP)
 procedure. PNF PnP is used to register PNF when it comes online.
 
 PRH Processing Flow
-===================
+-------------------
 
 .. image:: ../../images/prhAlgo.png
 
diff --git a/docs/sections/services/prh/authorization.rst b/docs/sections/services/prh/authorization.rst
new file mode 100644
index 00000000..fe5ed40b
--- /dev/null
+++ b/docs/sections/services/prh/authorization.rst
@@ -0,0 +1,60 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _authorization:
+
+SSL/TLS Authentication & Authorization
+======================================
+
+| PRH does not perform any authorization in AAF, as the only endpoint which is provided by the service is the healthcheck, which is unsecured.
+| For authentication settings there is a possibility to change from default behavior to certificate-based solution independently for DMaaP and AAI communication.
+
+AAI authentication
+^^^^^^^^^^^^^^^^^^
+
+Default
+"""""""
+| By default basic authentication is being used with following credentials:
+| user=AAI
+| password=AAI
+
+Certificate-based
+"""""""""""""""""
+| There is an option to enable certificate-based authentication for PRH towards AAI service calls.
+| To achieve this secure flag needs to be turned on in PRH :ref:`configuration<prh_configuration>` :
+
+.. code-block:: json
+  security.enableAaiCertAuth=true
+
+DMaaP BC authentication
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Default
+"""""""
+| By default basic authentication is being used with following credentials (for both DMaaP consumer and DMaaP publisher endpoints):
+| user=admin
+| password=admin
+
+Certificate-based
+""""""""""""""""""
+| There is an option to enable certificate-based authentication for PRH towards DMaaP Bus Controller service calls.
+| To achieve this secure flag needs to be turned on in PRH :ref:`configuration<prh_configuration>` :
+
+.. code-block:: json
+  --security.enableDmaapCertAuth=true
+
+PRH identity and certificate data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+| PRH is using ``dcae`` identity when certificate-based authentication is turned on.
+| It's the DCAEGEN2 responsibility to generate certificate for dcae identity and provide it to the collector.
+|
+| PRH by default expects that the volume ``tls-info`` is being mounted under path ``/opt/app/prh/etc/cert``.
+| It's the component/collector responsibility to provide necessary inputs in Cloudify blueprint to get the volume mounted.
+| See :doc:`../../tls_enablement` for detailed information.
+|
+| PRH is using four files from ``tls-info`` DCAE volume (``cert.jks, jks.pass, trust.jks, trust.pass``).
+| Refer :ref:`configuration<prh_configuration>` for proper security attributes settings.
+|
+| **IMPORTANT** Even when certificate-based authentication security features are disabled,
+| still all security settings needs to be provided in configuration to make PRH service start smoothly.
+| Security attributes values are not validated in this case, and can point to non-existent data.
diff --git a/docs/sections/services/prh/configuration.rst b/docs/sections/services/prh/configuration.rst
index a36ad953..0e4109cf 100644
--- a/docs/sections/services/prh/configuration.rst
+++ b/docs/sections/services/prh/configuration.rst
@@ -1,6 +1,8 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
+.. _prh_configuration:
+
 Configuration
 =============
 
@@ -8,46 +10,51 @@ PRH expects to be able to fetch configuration directly from consul service in fo
 
 .. code-block:: json
 
-    {
-        "dmaap.dmaapProducerConfiguration.dmaapTopicName":"/events/unauthenticated.PNF_READY",
-        "dmaap.dmaapConsumerConfiguration.dmaapHostName":"message-router.onap.svc.cluster.local",
-        "aai.aaiClientConfiguration.aaiPnfPath":"/network/pnfs/pnf",
-        "aai.aaiClientConfiguration.aaiUserPassword":"AAI",
-        "dmaap.dmaapConsumerConfiguration.dmaapUserName":"admin",
-        "aai.aaiClientConfiguration.aaiBasePath":"/aai/v12",
-        "dmaap.dmaapConsumerConfiguration.timeoutMs":-1,
-        "dmaap.dmaapProducerConfiguration.dmaapPortNumber":3904,
-        "aai.aaiClientConfiguration.aaiHost":"aai.onap.svc.cluster.local",
-        "dmaap.dmaapConsumerConfiguration.dmaapUserPassword":"admin",
-        "dmaap.dmaapProducerConfiguration.dmaapProtocol":"http",
-        "aai.aaiClientConfiguration.aaiIgnoreSslCertificateErrors":true,
-        "dmaap.dmaapProducerConfiguration.dmaapContentType":"application/json",
-        "dmaap.dmaapConsumerConfiguration.dmaapTopicName":"/events/unauthenticated.VES_PNFREG_OUTPUT",
-        "dmaap.dmaapConsumerConfiguration.dmaapPortNumber":3904,
-        "dmaap.dmaapConsumerConfiguration.dmaapContentType":"application/json",
-        "dmaap.dmaapConsumerConfiguration.messageLimit":-1,
-        "dmaap.dmaapConsumerConfiguration.dmaapProtocol":"http",
-        "aai.aaiClientConfiguration.aaiUserName":"AAI",
-        "dmaap.dmaapConsumerConfiguration.consumerId":"c12",
-        "dmaap.dmaapProducerConfiguration.dmaapHostName":"message-router.onap.svc.cluster.local",
-        "aai.aaiClientConfiguration.aaiHostPortNumber":8443,
-        "dmaap.dmaapConsumerConfiguration.consumerGroup":"OpenDCAE-c12",
-        "aai.aaiClientConfiguration.aaiProtocol":"https",
-        "dmaap.dmaapProducerConfiguration.dmaapUserName":"admin",
-        "dmaap.dmaapProducerConfiguration.dmaapUserPassword":"admin"
-    }
-
-
-There are also optional configuration parameters:
-
-.. code-block:: json
-
-   "security": {
-      "keyFile": "/opt/app/prh/local/org.onap.prh.keyfile",
-      "trustStore": "/opt/app/prh/local/org.onap.prh.trust.jks",
-      "trustStorePassword": "change it",
-      "keyStore": "/opt/app/prh/local/org.onap.prh.p12",
-      "keyStorePassword": "change it",
+  {
+    "aai": {
+      "aaiClientConfiguration": {
+        "aaiHost": "aai.onap.svc.cluster.local",
+        "aaiHostPortNumber": 8443,
+        "aaiIgnoreSslCertificateErrors": true,
+        "aaiProtocol": "https",
+        "aaiUserName": "AAI",
+        "aaiUserPassword": "AAI",
+        "aaiBasePath": "/aai/v12",
+        "aaiPnfPath": "/network/pnfs/pnf",
+      }
+    },
+    "dmaap": {
+      "dmaapConsumerConfiguration": {
+        "consumerGroup": "OpenDCAE-c12",
+        "consumerId": "c12",
+        "dmaapContentType": "application/json",
+        "dmaapHostName": "message-router.onap.svc.cluster.local",
+        "dmaapPortNumber": 3904,
+        "dmaapProtocol": "http",
+        "dmaapTopicName": "/events/unauthenticated.VES_PNFREG_OUTPUT",
+        "dmaapUserName": "admin",
+        "dmaapUserPassword": "admin",
+        "messageLimit": -1,
+        "timeoutMs": -1
+      },
+      "dmaapProducerConfiguration": {
+        "dmaapContentType": "application/json",
+        "dmaapHostName": "message-router.onap.svc.cluster.local",
+        "dmaapPortNumber": 3904,
+        "dmaapProtocol": "http",
+        "dmaapTopicName": "/events/unauthenticated.PNF_READY",
+        "dmaapUserName": "admin",
+        "dmaapUserPassword": "admin"
+      }
+    },
+    "security": {
+      "trustStorePath": "/opt/app/prh/etc/cert/trust.jks",
+      "trustStorePasswordPath": "/opt/app/prh/etc/cert/trust.pass",
+      "keyStorePath": "/opt/app/prh/etc/cert/cert.jks",
+      "keyStorePasswordPath": "/opt/app/prh/etc/cert/jks.pass",
       "enableAaiCertAuth": "false",
       "enableDmaapCertAuth": "false"
     }
+  }
+
+The configuration is created from PRH Cloudify blueprint by specifying **application_config** node during ONAP OOM/Kubernetes deployment.
diff --git a/docs/sections/services/prh/index.rst b/docs/sections/services/prh/index.rst
index d8a22e21..e3ba5bd9 100644
--- a/docs/sections/services/prh/index.rst
+++ b/docs/sections/services/prh/index.rst
@@ -14,13 +14,16 @@ the PNF Registration event.
 PRH overview and functions
 --------------------------
 
-
 .. toctree::
-    :maxdepth: 1
-       ./architecture.rst
-       ./configuration.rst
-       ./delivery.rst
-       ./installation.rst
+   :maxdepth: 1
+
+   ./architecture
+   ./configuration
+   ./delivery
+   ./installation
+   ./authorization
 
+API reference
+^^^^^^^^^^^^^
 
-.. _`Offered APIs`: ../../apis/prh.rst
\ No newline at end of file
+Refer to :doc:`PRH offered APIs<../../apis/PRH>` for detailed PRH api information.
diff --git a/docs/sections/services/prh/installation.rst b/docs/sections/services/prh/installation.rst
index aa65dadf..22dab33e 100644
--- a/docs/sections/services/prh/installation.rst
+++ b/docs/sections/services/prh/installation.rst
@@ -8,50 +8,56 @@ Following docker-compose-yaml file shows default configuration and can be run us
 
 .. code-block:: yaml
 
-version: '2'
-services:
-  prh:
-    image: nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.prh.prh-app-server
-    command: >
-      --dmaap.dmaapConsumerConfiguration.dmaapHostName=10.42.111.36
-      --dmaap.dmaapConsumerConfiguration.dmaapPortNumber=8904
-      --dmaap.dmaapConsumerConfiguration.dmaapTopicName=/events/unauthenticated.SEC_OTHER_OUTPUT
-      --dmaap.dmaapConsumerConfiguration.dmaapProtocol=http
-      --dmaap.dmaapConsumerConfiguration.dmaapUserName=admin
-      --dmaap.dmaapConsumerConfiguration.dmaapUserPassword=admin
-      --dmaap.dmaapConsumerConfiguration.dmaapContentType=application/json
-      --dmaap.dmaapConsumerConfiguration.consumerId=c12
-      --dmaap.dmaapConsumerConfiguration.consumerGroup=OpenDCAE-c12
-      --dmaap.dmaapConsumerConfiguration.timeoutMS=-1
-      --dmaap.dmaapConsumerConfiguration.message-limit=-1
-      --dmaap.dmaapProducerConfiguration.dmaapHostName=10.42.111.36
-      --dmaap.dmaapProducerConfiguration.dmaapPortNumber=8904
-      --dmaap.dmaapProducerConfiguration.dmaapTopicName=/events/unauthenticated.PNF_READY
-      --dmaap.dmaapProducerConfiguration.dmaapProtocol=http
-      --dmaap.dmaapProducerConfiguration.dmaapUserName=admin
-      --dmaap.dmaapProducerConfiguration.dmaapUserPassword=admin
-      --dmaap.dmaapProducerConfiguration.dmaapContentType=application/json
-      --aai.aaiClientConfiguration.aaiHostPortNumber=30233
-      --aai.aaiClientConfiguration.aaiHost=10.42.111.45
-      --aai.aaiClientConfiguration.aaiProtocol=https
-      --aai.aaiClientConfiguration.aaiUserName=admin
-      --aai.aaiClientConfiguration.aaiUserPassword=admin
-      --aai.aaiClientConfiguration.aaiIgnoreSSLCertificateErrors=true
-      --aai.aaiClientConfiguration.aaiBasePath=/aai/v11
-      --aai.aaiClientConfiguration.aaiPnfPath=/network/pnfs/pnf
-    entrypoint:
-      - java
-      - -Dspring.profiles.active=dev
-      - -jar
-      - /opt/prh-app-server.jar
-    ports:
-      - "8100:8100"
-      - "8433:8433"
-    restart: always
+  version: '3'
+  services:
+    prh:
+      image: nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.prh.prh-app-server
+      command: >
+        --dmaap.dmaapConsumerConfiguration.dmaapHostName=10.42.111.36
+        --dmaap.dmaapConsumerConfiguration.dmaapPortNumber=8904
+        --dmaap.dmaapConsumerConfiguration.dmaapTopicName=/events/unauthenticated.SEC_OTHER_OUTPUT
+        --dmaap.dmaapConsumerConfiguration.dmaapProtocol=http
+        --dmaap.dmaapConsumerConfiguration.dmaapUserName=admin
+        --dmaap.dmaapConsumerConfiguration.dmaapUserPassword=admin
+        --dmaap.dmaapConsumerConfiguration.dmaapContentType=application/json
+        --dmaap.dmaapConsumerConfiguration.consumerId=c12
+        --dmaap.dmaapConsumerConfiguration.consumerGroup=OpenDCAE-c12
+        --dmaap.dmaapConsumerConfiguration.timeoutMS=-1
+        --dmaap.dmaapConsumerConfiguration.message-limit=-1
+        --dmaap.dmaapProducerConfiguration.dmaapHostName=10.42.111.36
+        --dmaap.dmaapProducerConfiguration.dmaapPortNumber=8904
+        --dmaap.dmaapProducerConfiguration.dmaapTopicName=/events/unauthenticated.PNF_READY
+        --dmaap.dmaapProducerConfiguration.dmaapProtocol=http
+        --dmaap.dmaapProducerConfiguration.dmaapUserName=admin
+        --dmaap.dmaapProducerConfiguration.dmaapUserPassword=admin
+        --dmaap.dmaapProducerConfiguration.dmaapContentType=application/json
+        --aai.aaiClientConfiguration.aaiHostPortNumber=30233
+        --aai.aaiClientConfiguration.aaiHost=10.42.111.45
+        --aai.aaiClientConfiguration.aaiProtocol=https
+        --aai.aaiClientConfiguration.aaiUserName=admin
+        --aai.aaiClientConfiguration.aaiUserPassword=admin
+        --aai.aaiClientConfiguration.aaiIgnoreSSLCertificateErrors=true
+        --aai.aaiClientConfiguration.aaiBasePath=/aai/v11
+        --aai.aaiClientConfiguration.aaiPnfPath=/network/pnfs/pnf
+        --security.enableAaiCertAuth=false
+        --security.enableDmaapCertAuth=false
+        --security.keyStorePath=/opt/app/prh/etc/cert/cert.jks
+        --security.keyStorePasswordPath=/opt/app/prh/etc/cert/jks.pass
+        --security.trustStorePath=/opt/app/prh/etc/cert/trust.jks
+        --security.trustStorePasswordPath=/opt/app/prh/etc/cert/trust.pass
+      entrypoint:
+        - java
+        - -Dspring.profiles.active=dev
+        - -jar
+        - /opt/prh-app-server.jar
+      ports:
+        - "8100:8100"
+        - "8433:8433"
+      restart: always
 
 
 Running with dev-mode of PRH
-==============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Heartbeat: http://<container_address>:8100/heartbeat or https://<container_address>:8443/heartbeat