security related documentation moved to buscontroller

Change-Id: I4e184d85555d565c77639db61f5d5261f01435e6
Issue-ID: DMAAP-1115
Signed-off-by: piotr.karas <piotr.karas@nokia.com>

2 files changed, 179 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 545ee5f..121f062 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,4 +17,5 @@ dmaap/buscontroller
    administration/administration.rst
    logging/logging.rst
    delivery/delivery.rst
+   security/security.rst
 
diff --git a/docs/security/security.rst b/docs/security/security.rst
new file mode 100644
index 0000000..1c11fce
--- /dev/null
+++ b/docs/security/security.rst
@@ -0,0 +1,178 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Security
+=========
+
+.. contents:: Table of Contents
+
+SSL DmaaP Certificates and Configuration
+----------------------------------------
+
+Configuration related to ssl can be found in the ``dmaapbc.properties``.
+File is located in the ``/opt/app/dmaapbc/etc`` on the dmaap-bc pod. Directory contains also truststore and keystore files used in the ssl setup.
+Each change in the configuration file requires restart of the application container
+
+.. code-block:: bash
+
+    #
+    #	Allow http access to API
+    #
+    HttpAllowed:	true
+    #
+    #	The port number for http as seen within the server
+    #
+    IntHttpPort:	8080
+    #
+    #	The port number for https as seen within the server
+    #   Set to 0 if no certificate is available yet...
+    #
+    IntHttpsPort:	8443
+    #
+    #	The external port number for https taking port mapping into account
+    #
+    ExtHttpsPort:	443
+    #
+    #	The type of keystore for https
+    #
+    KeyStoreType:	jks
+    #
+    #	The path to the keystore for https
+    #
+    KeyStoreFile:	etc/keystore
+    #
+    #	The password for the https keystore
+    #
+    KeyStorePassword:	<keystore_password>
+    #
+    #	The password for the private key in the https keystore
+    #
+    KeyPassword:	<key_password>
+    #
+    #	The type of truststore for https
+    #
+    TrustStoreType:	jks
+    #
+    #	The path to the truststore for https
+    #
+    TrustStoreFile:	etc/org.onap.dmaap-bc.trust.jks
+    #
+    #	The password for the https truststore
+    #
+    TrustStorePassword:	<truststore_password>
+
+
+AAF configuration
+-----------------
+
+Usage of AAF can be turned on/off by setting ``UseAAF`` flag to ``true/false`` in the ``dmaapbc.properties`` file. By default AFF usage is turned on.
+Property ``cadi.properties`` points to absolute path of the property file generated by AAF for the DmaaP BC application (``dmaap-bc@dmaap-bc.onap.org`` user).
+This file is one of the AAF configuration files enabling authentication and authorization for DmaaP BC REST API.
+
+.. code-block:: bash
+
+    #################
+    # AAF Properties:
+    UseAAF: true
+
+    #################
+    #
+    # path to cadi.properties
+    #
+    cadi.properties: /opt/app/osaaf/local/org.onap.dmaap-bc.props
+
+
+Complete AAF configuration consist of following files:
+    - org.onap.dmaap-bc.props - main configuration file
+    - org.onap.dmaap-bc.location.props - geographic coordinates of the application
+    - org.onap.dmaap-bc.cred.props - properties related to credentials, keystore and truststore
+    - org.onap.dmaap-bc.keyfile - keyfile
+    - org.onap.dmaap-bc.p12 - keystore
+    - org.onap.dmaap-bc.trust.jks - truststore
+
+
+All listed files are located in the ``/opt/app/dmaapbc/etc`` directory.
+File ``org.onap.dmaap-bc.props`` links together all property files by defining them in the ``cadi_prop_files`` property.
+By default all paths to other AAF related configuration points to ``/opt/app/osaaf/local/`` directory.
+This directory is default location that can be changed during generation of configuration files in the AAF application.
+In order to not duplicate mentioned files on the dmaap-bc pod following symbolic link is created in the filesystem:
+
+.. code-block:: bash
+
+    ln -s /opt/app/dmaapbc/etc /opt/app/osaaf/local
+
+
+User configured and used in DmaaP BC
+------------------------------------
+
+dmaap-bc@dmaap-bc.onap.org
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is main user for the DmaaP BC application. It has permissions to validate if user accessing DmaaP BC REST api has appropriate permissions to
+perform an action.
+
+
+AAF Permissions
++++++++++++++++
+
+.. code-block:: bash
+
+    List Permissions by User[dmaap-bc@dmaap-bc.onap.org]
+    --------------------------------------------------------------------------------
+    PERM Type                      Instance                       Action
+    --------------------------------------------------------------------------------
+    org.onap.dmaap-bc.api.access   *                              read
+    org.onap.dmaap-bc.certman      local                          request,ignoreIPs,showpass
+    org.onap.dmaap-dr.feed         *                              *
+    org.onap.dmaap-dr.sub          *                              *
+    org.onap.dmaap.mr.access       *                              *
+    org.onap.dmaap.mr.topic        *                              *
+    org.onap.dmaap.mr.topic        *                              view
+    org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr create,destroy
+
+
+dmaap-bc-topic-mgr@dmaap-bc-topic-mgr.onap.org
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``UseAAF`` is set to true then creating topic also will create required perms in AAF. The perms will be created in ``org.onap.dmaap.mr`` namespace.
+User ``dmaap-bc-topic-mgr`` is used in the process of creating such permissions.
+
+**Example:**
+    Topic name:
+        aSimpleTopic
+
+    Permissions
+        org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|pub org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|sub org.onap.dmaap.mr.topic|:topic.org.onap.dmaap.mr.aSimpleTopic|view
+
+
+AAF Permissions
++++++++++++++++
+
+.. code-block:: bash
+
+    List Permissions by User[dmaap-bc-topic-mgr@dmaap-bc-topic-mgr.onap.org]
+    ---------------------------------------------------------------------------------------
+    PERM Type                                  Instance                       Action
+    ---------------------------------------------------------------------------------------
+    org.onap.dmaap-dr.feed                     *                              *
+    org.onap.dmaap-dr.sub                      *                              *
+    org.onap.dmaap.mr.PNF_READY.access         *                              *
+    org.onap.dmaap.mr.PNF_REGISTRATION.access  *                              *
+    org.onap.dmaap.mr.access                   *                              *
+    org.onap.dmaap.mr.dgl_ready.access         *                              *
+    org.onap.dmaap.mr.mirrormaker              *                              admin
+    org.onap.dmaap.mr.mirrormaker              *                              user
+    org.onap.dmaap.mr.topic                    *                              view
+    org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.mirrormakeragent pub
+    org.onap.dmaap.mr.topic        :topic.org.onap.dmaap.mr.mirrormakeragent sub
+    org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr create
+    org.onap.dmaap.mr.topicFactory :org.onap.dmaap.mr.topic:org.onap.dmaap.mr destroy
+
+
+aaf_admin@people.osaaf.org
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This user is used in the process of the post-installation during which appropriate namespaces and permissions are created in AAF.
+
+
+