From 3c935a82d1ce444bc49b2163ebe2dd2311d86bc6 Mon Sep 17 00:00:00 2001 From: John Vrbanac Date: Wed, 18 Mar 2015 18:35:39 -0500 Subject: [PATCH] Starting to rework docs around the secret resource This is the start of a reworking of our docs around the secrets API. There will be a number of follow-up patches before this document will be considered complete. Until this document is considered complete, I'm not adding this page to the table of contents. Also, to limit individual CR size, I've tossed TODOs on the areas that will be worked on in future CRs. Change-Id: I8599628d51f4b5aae9ec1b8fd76f419d5b38bdcc --- doc/source/api/index.rst | 21 ++++ doc/source/api/quickstart/secrets.rst | 34 +++++++ doc/source/api/reference/secrets.rst | 137 ++++++++++++++++++++++++++ 3 files changed, 192 insertions(+) create mode 100644 doc/source/api/index.rst create mode 100644 doc/source/api/quickstart/secrets.rst create mode 100644 doc/source/api/reference/secrets.rst diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 000000000..7c5d249d0 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,21 @@ +************************** +Barbican API Documentation +************************** + +Quick Start +########### + +.. toctree:: + :maxdepth: 1 + + ./quickstart/secrets + + +API Reference +############# + +.. toctree:: + :maxdepth: 1 + + ./reference/secrets + diff --git a/doc/source/api/quickstart/secrets.rst b/doc/source/api/quickstart/secrets.rst new file mode 100644 index 000000000..d86194d8c --- /dev/null +++ b/doc/source/api/quickstart/secrets.rst @@ -0,0 +1,34 @@ +************************* +Secrets API - Quick Start +************************* + +The secrets resource is the heart of the Barbican service. It provides access +to the secret / keying material stored in the system. + +Barbican supports the storage of data for various content-types securely. + +TODO(jvrbanac): Add more information about the secrets resource + + +What is a secret +################ + +TODO(jvrbanac): Add a summary here + + +How to create a secret +###################### +TODO(jvrbanac): Add examples + +How to update a secret +###################### +TODO(jvrbanac): Add examples + +How to retrieve a secret +######################## +TODO(jvrbanac): Add examples + +How to delete a secret +###################### +TODO(jvrbanac): Add examples + diff --git a/doc/source/api/reference/secrets.rst b/doc/source/api/reference/secrets.rst new file mode 100644 index 000000000..d02e3d24b --- /dev/null +++ b/doc/source/api/reference/secrets.rst @@ -0,0 +1,137 @@ +*********************** +Secrets API - Reference +*********************** + +GET /secrets +############ +Lists a project's secrets. + +The list of secrets can be filtered by the parameters passed in via the URL. + +Parameters +********** + ++--------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++========+=========+================================================================+ +| offset | integer | The starting index within the total list of the secrets that | +| | | you would like to retrieve. | ++--------+---------+----------------------------------------------------------------+ +| limit | integer | The maximum number of records to return (up to 100). The | +| | | default limit is 10. | ++--------+---------+----------------------------------------------------------------+ +| name | string | Selects all secrets with name equal to this value. | ++--------+---------+----------------------------------------------------------------+ +| bits | integer | Selects all secrets with bit_length equal to this value. | ++--------+---------+----------------------------------------------------------------+ +| alg | string | Selects all secrets with algorithm equal to this value. | ++--------+---------+----------------------------------------------------------------+ +| mode | string | Selects all secrets with mode equal to this value. | ++--------+---------+----------------------------------------------------------------+ + +Response Attributes +******************* + ++----------+---------+--------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+==============================================================+ +| secrets | list | Contains a list of dictionaries filled with secret metadata. | ++----------+---------+--------------------------------------------------------------+ +| total | integer | The total number of secrets available to the user. | ++----------+---------+--------------------------------------------------------------+ +| next | string | A HATEOS url to retrieve the next set of secrets based on | +| | | the offset and limit parameters. This attribute is only | +| | | available when the total number of secrets is greater than | +| | | offset and limit parameter combined. | ++----------+---------+--------------------------------------------------------------+ +| previous | string | A HATEOS url to retrieve the previous set of secrets based | +| | | on the offset and limit parameters. This attribute is only | +| | | available when the request offset is greater than 0. | ++----------+---------+--------------------------------------------------------------+ + + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | Successful Request | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource | ++------+-----------------------------------------------------------------------------+ + + +POST /secrets +############# +Creates a secret + +Attributes +********** + ++----------------------------+---------+----------------------------------------------+------------+ +| Attribute Name | Type | Description | Default | ++============================+=========+==============================================+============+ +| name | string | (optional) The name of the secret set by the | None | +| | | user. | | ++----------------------------+---------+----------------------------------------------+------------+ +| expiration | string | (optional) This is a timestamp in ISO 8601 | None | +| | | format ``YYYY-MM-DDTHH:MM:SSZ.`` | | ++----------------------------+---------+----------------------------------------------+------------+ +| algorithm | string | (optional) Metadata provided by a user or | None | +| | | system for informational purposes. | | ++----------------------------+---------+----------------------------------------------+------------+ +| bit_length | integer | (optional) Metadata provided by a user or | None | +| | | system for informational purposes. | | ++----------------------------+---------+----------------------------------------------+------------+ +| mode | string | (optional) Metadata provided by a user or | None | +| | | system for informational purposes. | | ++----------------------------+---------+----------------------------------------------+------------+ +| payload | string | (optional) The secret's data to be stored. | None | +| | | ``payload_content_type`` must also be | | +| | | supplied if payload is provided. | | ++----------------------------+---------+----------------------------------------------+------------+ +| payload_content_type | string | (optional) (required if payload is added) | None | +| | | The type and format of the secret data. The | | +| | | two supported types are ``text/plain`` and | | +| | | ``application/octet-stream``. | | ++----------------------------+---------+----------------------------------------------+------------+ +| payload_content_encoding | string | (optional) The encoding used to format the | None | +| | | payload provided. Currently only base64 is | | +| | | supported. This is required if content type | | +| | | provided has an encoding available. | | ++----------------------------+---------+----------------------------------------------+------------+ +| secret_type | string | (optional) Used to indicate the type of | ``opaque`` | +| | | secret being stored. If no value is given, | | +| | | ``opaque`` is used as the default, which is | | +| | | used to signal Barbican to just store the | | +| | | information without worrying about format or | | +| | | encoding. | | ++----------------------------+---------+----------------------------------------------+------------+ + +TODO(jvrbanac): Finish this section + +GET /secrets/{uuid} +################### +Retrieves a secret's metadata by uuid + +TODO(jvrbanac): Finish this section + +DELETE /secrets/{uuid} +###################### + +Delete a secret by uuid + +TODO(jvrbanac): Finish this section + +GET /secrets/{uuid}/payload +########################### +Retrieve a secret's payload + +TODO(jvrbanac): Finish this section + +PUT /secrets/{uuid}/payload +########################### +Update a secret's payload + +TODO(jvrbanac): Finish this section