diff options
author | Kiran Kamineni <kiran.k.kamineni@intel.com> | 2018-05-04 16:50:39 -0700 |
---|---|---|
committer | Girish Havaldar <hg0071052@techmahindra.com> | 2018-05-15 17:21:53 +0000 |
commit | ac134cb099afa6be09fbc5cdad5db0bcf7aee08a (patch) | |
tree | cbcdf280db9285edfe8c6e62e094c6c4c6db302e | |
parent | d4b81c05a255a847bbf7f08caebe032492ad2ca5 (diff) |
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>
-rw-r--r-- | docs/api_swagger.html (renamed from sms-service/doc/api_swagger.html) | 0 | ||||
-rw-r--r-- | docs/api_swagger.yaml (renamed from sms-service/doc/api_swagger.yaml) | 0 | ||||
-rw-r--r-- | docs/apiswagger.rst | 745 | ||||
-rw-r--r-- | docs/coverage.html (renamed from sms-service/doc/coverage.html) | 0 | ||||
-rw-r--r-- | docs/coverage.md (renamed from sms-service/doc/coverage.md) | 0 | ||||
-rw-r--r-- | docs/index.rst | 37 | ||||
-rw-r--r-- | docs/installation.rst | 33 | ||||
-rw-r--r-- | docs/sms_high_level.png | bin | 0 -> 141997 bytes | |||
-rw-r--r-- | docs/usage.rst | 54 |
9 files changed, 869 insertions, 0 deletions
diff --git a/sms-service/doc/api_swagger.html b/docs/api_swagger.html index 7f987a3..7f987a3 100644 --- a/sms-service/doc/api_swagger.html +++ b/docs/api_swagger.html diff --git a/sms-service/doc/api_swagger.yaml b/docs/api_swagger.yaml index 61cd091..61cd091 100644 --- a/sms-service/doc/api_swagger.yaml +++ b/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 <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 index 39ee191..39ee191 100644 --- a/sms-service/doc/coverage.html +++ b/docs/coverage.html diff --git a/sms-service/doc/coverage.md b/docs/coverage.md index 6168342..6168342 100644 --- a/sms-service/doc/coverage.md +++ b/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 Binary files differnew file mode 100644 index 0000000..3cd14ba --- /dev/null +++ b/docs/sms_high_level.png 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/<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 |