From: Kiran Kamineni Date: Fri, 4 May 2018 23:50:39 +0000 (-0700) Subject: Adding a docs folder under sms repo X-Git-Tag: 2.0.0-ONAP~12 X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F15%2F46315%2F3;p=aaf%2Fsms.git 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 --- 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 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 `_ + + + + +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 ` + +**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 ` + +**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 ` | | | 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 `"} + +.. 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 ` | | | 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 `"} + +.. 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 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 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 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 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/