Adding a docs folder under sms repo

WORK IN PROGRESS
Adding a docs folder under sms

Issue-ID: AAF-185
Change-Id: I5ee3560cfda2100ad5207bb7e98d5cb9472e1325
Signed-off-by: Girish Havaldar <hg0071052@techmahindra.com>

diff --git a/sms-service/doc/api_swagger.html b/docs/api_swagger.html
similarity index 100%
rename from sms-service/doc/api_swagger.html
rename to docs/api_swagger.html

diff --git a/sms-service/doc/api_swagger.yaml b/docs/api_swagger.yaml
similarity index 100%
rename from sms-service/doc/api_swagger.yaml
rename to docs/api_swagger.yaml

diff --git a/docs/apiswagger.rst b/docs/apiswagger.rst
new file mode 100644 (file)
index 0000000..e35c6e8
--- /dev/null
+++ b/docs/apiswagger.rst
@@ -0,0 +1,745 @@
+SMS 1.0.0 API
+===============================
+
+.. toctree::
+    :maxdepth: 3
+
+
+Description
+~~~~~~~~~~~
+
+This is a service that provides secret management facilities
+
+
+
+Contact Information
+~~~~~~~~~~~~~~~~~~~
+
+
+
+kiran.k.kamineni@intel.com
+
+
+
+
+
+License
+~~~~~~~
+
+
+`Apache 2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_
+
+
+
+
+Base URL
+~~~~~~~~
+
+https://aaf.onap.org:10443/v1/sms/
+
+Security
+~~~~~~~~
+
+
+.. _securities_token:
+
+token (API Key)
+---------------
+
+
+
+**Name:** token
+
+**Located in:** header
+
+
+
+
+DOMAIN
+~~~~~~
+
+
+Operations related to Secret Domains
+
+
+
+
+
+DELETE ``/domain/{domainName}``
+-------------------------------
+
+
+Summary
++++++++
+
+Deletes a domain by name
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Deletes a domain with provided name
+
+Parameters
+++++++++++
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 15, 10, 10, 10, 20, 30
+
+        domainName | path | Yes | string |  |  | Name of the domain
+
+
+Request
++++++++
+
+
+Responses
++++++++++
+
+**204**
+^^^^^^^
+
+Successful Deletion
+
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+
+
+POST ``/domain``
+----------------
+
+
+Summary
++++++++
+
+Add a new domain
+
+
+
+Request
++++++++
+
+
+
+.. _d_c7bdcff9aff0692da98e588abdbc895b:
+
+Body
+^^^^
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        name | No | string |  |  | Name of the secret domain under which all secrets will be stored
+        uuid | No | string |  |  | Optional value provided by user. If user does not provide, server will auto generate
+
+.. code-block:: javascript
+
+    {
+        "name": "somestring", 
+        "uuid": "somestring"
+    }
+
+Responses
++++++++++
+
+**201**
+^^^^^^^
+
+Successful Creation
+
+
+Type: :ref:`Domain <d_c7bdcff9aff0692da98e588abdbc895b>`
+
+**Example:**
+
+.. code-block:: javascript
+
+    {
+        "name": "somestring", 
+        "uuid": "somestring"
+    }
+
+**400**
+^^^^^^^
+
+Invalid input
+
+
+**500**
+^^^^^^^
+
+Internal Server Error
+
+
+
+
+  
+LOGIN
+~~~~~
+
+
+Operations related to username password based authentication
+
+
+
+
+
+POST ``/login``
+---------------
+
+
+Summary
++++++++
+
+Login with username and password
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Operations related to logging in via username and Password
+
+
+Request
++++++++
+
+
+
+.. _d_8e36d758bad367e4538a291a5dd5355f:
+
+Body
+^^^^
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        password | No | string |  |  | 
+        username | No | string |  |  | 
+
+.. code-block:: javascript
+
+    {
+        "password": "somestring", 
+        "username": "somestring"
+    }
+
+Responses
++++++++++
+
+**200**
+^^^^^^^
+
+Successful Login returns a token
+
+
+.. _i_bbceffdf8441c1c476ca77c42ad12f85:
+
+**Response Schema:**
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        token | No | string |  |  | 
+        ttl | No | integer |  |  | ttl of returned token in seconds
+
+
+**Example:**
+
+.. code-block:: javascript
+
+    {
+        "token": "somestring", 
+        "ttl": 1
+    }
+
+**404**
+^^^^^^^
+
+Invalid Username or Password
+
+
+
+
+  
+SECRET
+~~~~~~
+
+
+Operations related to Secrets
+
+
+
+
+
+DELETE ``/domain/{domainName}/secret/{secretName}``
+---------------------------------------------------
+
+
+Summary
++++++++
+
+Deletes a Secret
+
+
+Parameters
+++++++++++
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 15, 10, 10, 10, 20, 30
+
+        secretName | path | Yes | string |  |  | Name of Secret to Delete
+        domainName | path | Yes | string |  |  | Path to the SecretDomain which contains the Secret
+
+
+Request
++++++++
+
+
+Responses
++++++++++
+
+**204**
+^^^^^^^
+
+Successful Deletion
+
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+
+
+GET ``/domain/{domainName}/secret``
+-----------------------------------
+
+
+Summary
++++++++
+
+List secret Names in this domain
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Gets all secret names in this domain
+
+Parameters
+++++++++++
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 15, 10, 10, 10, 20, 30
+
+        domainName | path | Yes | string |  |  | Name of the domain in which to look at
+
+
+Request
++++++++
+
+
+Responses
++++++++++
+
+**200**
+^^^^^^^
+
+Successful operation
+
+
+.. _i_1dcddfd6f11cba3fb2516d3a61cd1b77:
+
+**Response Schema:**
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        secretnames | No | array of string |  |  | Array of strings referencing the secret names
+
+
+**Example:**
+
+.. code-block:: javascript
+
+    {
+        "secretnames": [
+            "secretname1", 
+            "secretname2", 
+            "secretname3"
+        ]
+    }
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+
+
+GET ``/domain/{domainName}/secret/{secretName}``
+------------------------------------------------
+
+
+Summary
++++++++
+
+Find Secret by Name
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Returns a single secret
+
+Parameters
+++++++++++
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 15, 10, 10, 10, 20, 30
+
+        domainName | path | Yes | string |  |  | Name of the domain in which to look at
+        secretName | path | Yes | string |  |  | Name of the secret which is needed
+
+
+Request
++++++++
+
+
+Responses
++++++++++
+
+**200**
+^^^^^^^
+
+successful operation
+
+
+Type: :ref:`Secret <d_5e5fddd9ede6eb091e8496a9c55b84c3>`
+
+**Example:**
+
+.. code-block:: javascript
+
+    {
+        "name": "somestring", 
+        "values": {
+            "Age": 40, 
+            "admin": true, 
+            "name": "john"
+        }
+    }
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+
+
+POST ``/domain/{domainName}/secret``
+------------------------------------
+
+
+Summary
++++++++
+
+Add a new secret
+
+
+Parameters
+++++++++++
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Located in", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 15, 10, 10, 10, 20, 30
+
+        domainName | path | Yes | string |  |  | Name of the domain
+
+
+Request
++++++++
+
+
+
+.. _d_5e5fddd9ede6eb091e8496a9c55b84c3:
+
+Body
+^^^^
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        name | No | string |  |  | Name of the secret
+        values | No | :ref:`values <i_a9213c9639162b77082e257e19cca0d0>` |  |  | Map of key value pairs that constitute the secret
+
+.. _i_a9213c9639162b77082e257e19cca0d0:
+
+**Values schema:**
+
+
+Map of key value pairs that constitute the secret
+
+Map of {"key":":ref:`values-mapped <m_4d863967ef9a9d9efdadd1b250c76bd6>`"}
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+
+
+.. code-block:: javascript
+
+    {
+        "name": "somestring", 
+        "values": {
+            "Age": 40, 
+            "admin": true, 
+            "name": "john"
+        }
+    }
+
+Responses
++++++++++
+
+**201**
+^^^^^^^
+
+Successful Creation
+
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+  
+SYSTEM
+~~~~~~
+
+
+Operations related to quorum client which are not useful to clients
+
+
+
+
+
+GET ``/status``
+---------------
+
+
+Summary
++++++++
+
+Get backend status
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Gets current backend status. This API is used only by quorum clients
+
+
+Request
++++++++
+
+
+Responses
++++++++++
+
+**200**
+^^^^^^^
+
+Successful operation
+
+
+.. _i_ac1bc8e82eadbd8c03f852e15be4d03b:
+
+**Response Schema:**
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        sealstatus | No | string |  |  | seal status of backend
+
+
+**Example:**
+
+.. code-block:: javascript
+
+    {
+        "sealstatus": "somestring"
+    }
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+
+
+POST ``/unseal``
+----------------
+
+
+Summary
++++++++
+
+Unseal backend
+
+Description
++++++++++++
+
+.. raw:: html
+
+    Sends unseal shard to unseal if backend is sealed
+
+
+Request
++++++++
+
+
+
+.. _i_9d32e021ba68855cbb6e633520b7cd2d:
+
+Body
+^^^^
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        unsealshard | No | string |  |  | Unseal shard that will be used along with other shards to unseal backend
+
+.. code-block:: javascript
+
+    {
+        "unsealshard": "somestring"
+    }
+
+Responses
++++++++++
+
+**201**
+^^^^^^^
+
+Submitted unseal key
+
+
+**404**
+^^^^^^^
+
+Invalid Path or Path not found
+
+
+
+
+  
+Data Structures
+~~~~~~~~~~~~~~~
+
+.. _d_8e36d758bad367e4538a291a5dd5355f:
+
+Credential Model Structure
+--------------------------
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        password | No | string |  |  | 
+        username | No | string |  |  | 
+
+.. _d_c7bdcff9aff0692da98e588abdbc895b:
+
+Domain Model Structure
+----------------------
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        name | No | string |  |  | Name of the secret domain under which all secrets will be stored
+        uuid | No | string |  |  | Optional value provided by user. If user does not provide, server will auto generate
+
+.. _d_5e5fddd9ede6eb091e8496a9c55b84c3:
+
+Secret Model Structure
+----------------------
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+        name | No | string |  |  | Name of the secret
+        values | No | :ref:`values <i_a9213c9639162b77082e257e19cca0d0>` |  |  | Map of key value pairs that constitute the secret
+
+.. _i_a9213c9639162b77082e257e19cca0d0:
+
+**Values schema:**
+
+
+Map of key value pairs that constitute the secret
+
+Map of {"key":":ref:`values-mapped <m_4d863967ef9a9d9efdadd1b250c76bd6>`"}
+
+.. csv-table::
+    :delim: |
+    :header: "Name", "Required", "Type", "Format", "Properties", "Description"
+    :widths: 20, 10, 15, 15, 30, 25
+
+
+

diff --git a/sms-service/doc/coverage.html b/docs/coverage.html
similarity index 100%
rename from sms-service/doc/coverage.html
rename to docs/coverage.html

diff --git a/sms-service/doc/coverage.md b/docs/coverage.md
similarity index 100%
rename from sms-service/doc/coverage.md
rename to docs/coverage.md

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644 (file)
index 0000000..5f17a04
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,37 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Intel Corporation, Inc
+
+SMS-Secret Management Service
+==================================
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   usage
+   apiswagger
+
+
+Introduction
+------------
+
+This project aims at the Storage of sensitive information such as passwords.
+
+**Current state and gaps**
+
+Many services in ONAP use password based authentication. Eg: Database servers, publish/subscribe brokers etc.
+Passwords are stored in plain text files in many services.
+With multiple instances of these services, the attach surface area becomes very big.
+Hence there is a need to ensure that attack surface related to password exposure is reduced.
+
+**Requirement:**
+
+Need for secure secret management. Services are expected to get the secret only on needed basis using secret reference and remove the secrets once they are used up.
+
+**Secret Service High Level Flow Diagram**
+
+.. image:: sms_high_level.png
+   :width: 4555550px
+   :height: 300px
+   :alt: SMS Flow Diagram

diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644 (file)
index 0000000..b22d133
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,33 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Intel Corporation, Inc
+
+Installation
+============
+
+The Secret Managment Project is a subproject of AAF and will deployed via Helm on Kubernetes
+under the OOM Project
+
+.. code-block:: console
+
+    # Set Datastore as Consul
+    DATASTORE="consul"
+    # Set IP address of where Consul is running
+    DATASTORE_IP="localhost"
+    # Set mountpath inside the container where persistent data is stored.
+    MOUNTPATH="/dkv_mount_path/configs/"
+    # Place all Config data which needs to be loaded in default directory.
+    DEFAULT_CONFIGS=$(pwd)/mountpath/default
+    # Create the directories.
+    mkdir -p mountpath/default
+    # Login to Nexus.
+    docker login -u docker -p docker nexus3.onap.org:10001
+    # Pull distributed-kv-store image.
+    docker pull nexus3.onap.org:10001/onap/music/distributed-kv-store
+    # Run the distributed-kv-store image.
+    docker run -e DATASTORE=$DATASTORE -e DATASTORE_IP=$DATASTORE_IP -e MOUNTPATH=$MOUNTPATH -d \
+           --name dkv \
+           -v $DEFAULT_CONFIGS:/dkv_mount_path/configs/default \
+           -p 8200:8200 -p 8080:8080 nexus3.onap.org:10001/onap/music/distributed-kv-store
+
+.. end

diff --git a/docs/sms_high_level.png b/docs/sms_high_level.png
new file mode 100644 (file)
index 0000000..3cd14ba
Binary files /dev/null and b/docs/sms_high_level.png differ

diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644 (file)
index 0000000..b35e9b5
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,54 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Intel Corporation, Inc
+
+Typical Usage Scenario
+======================
+
+.. code-block:: guess
+
+    ## Create a Domain
+    ## This is where all your secrets will be stored
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X POST \
+        -d '{
+                "name": "mysecretdomain"
+            }'
+        https://sms:10443/v1/sms/domain
+
+    ## Add a new Secret
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X POST \
+        -d '{
+                "name": "mysecret",
+                "values": {
+                    "name": "rah",
+                    "age": 35,
+                    "password": "mypassword"
+                }
+            }'
+        https://sms:10443/v1/sms/domain/<domaincurltestdomain/secret
+
+
+    ## List all Secrets under a Domain
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X GET \
+        https://sms:10443/v1/sms/domain/curltestdomain/secret
+
+    ## Get a Secret in a Domain
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X GET \
+        https://sms:10443/v1/sms/domain/curltestdomain/secret/curltestsecret1
+
+    ## Delete a Secret in specified Domain
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X DELETE \
+        https://sms:10443/v1/sms/domain/curltestdomain/secret/curltestsecret1
+
+    ## Delete a Domain
+    ## This will delete all the secrets in that Domain
+    curl -H "Accept: application/json" --cacert ca.pem --cert client.cert --key client.key
+        -X DELETE \
+        https://sms:10443/v1/sms/domain/curltestdomain
+
+.. end