*************************
Secrets API - User Guide
*************************

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.

This guide will assume you will be using a local running development environment of barbican.
If you need assistance with getting set up, please reference the
`development guide <https://docs.openstack.org/barbican/latest/contributor/dev.html>`__.


What is a Secret?
#################

A secret is a singular item that is stored within barbican. A secret is
anything you want it to be; however, the formal use case is a key that you wish
to store away from prying eyes.

Some examples of a secret may include:
  * Private Key
  * Certificate
  * Password
  * SSH Keys

For the purpose of this user guide, we will use a simple plaintext
secret. If you would like to learn more in detail about
`secret parameters <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#secret-parameters>`__,
`responses <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#secret_response_attributes>`__,
and `status codes <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#secret_status_codes>`__
you can reference the
`secret reference <https://docs.openstack.org/barbican/latest/api/reference/secrets.html>`__
documentation.


.. _create_secret:

How to Create a Secret
######################

Single Step Secret Creation
***************************

The first secret we will create is a single step secret. Using a single step,
barbican expects the user to provide the payload to be stored within the secret
itself. Once the secret has been created with a payload it cannot be updated. In
this example we will provide a plain text secret. For more information on creating
secrets you can view the
`POST /v1/secrets <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#post-secrets>`__
section.

.. code-block:: bash

    curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
    -d '{"payload": "my-secret-here", "payload_content_type": "text/plain"}' \
    http://localhost:9311/v1/secrets

This should provide a response as follows:

.. code-block:: bash

    {"secret_ref": "http://localhost:9311/v1/secrets/2a549393-0710-444b-8aa5-84cf0f85ea79"}

This is our secret reference. We will need this in order to retrieve the secret in the following steps.
Jump ahead to :ref:`How to Retrieve a Secret <retrieve_secret>` to make sure our secret is
stored as expected.

.. _two_step_secret_create:

Two Step Secret Creation
************************

The second secret we will create is a two-step secret. A two-step secret will
allow the user to create a secret reference initially, but upload the secret
data after the fact. In this example we will not provide a payload.

.. code-block:: bash

    curl -X POST -H "content-type:application/json" -H "X-Auth-Token: $TOKEN" \
    -d '{}' http://localhost:9311/v1/secrets

This should provide a response as follows:

.. code-block:: bash

    {"secret_ref": "http://localhost:9311/v1/secrets/2a549393-0710-444b-8aa5-84cf0f85ea79"}

Now that we have a secret reference available, we can update the secret data.

.. _update_secret:

How to Update a Secret
######################

To update the secret data we will need to know the secret reference provided
via the initial creation. (See :ref:`Two Step Secret Creation <two_step_secret_create>`
for more information.) In the example below, the secret ref is used from the
previous example. You will have to substitute the uuid after /secrets/ with
your own in order to update the secret.

.. code-block:: bash

    curl -X PUT -H "content-type:text/plain" -H "X-Auth-Token: $TOKEN" \
    -d 'my-secret-here' \
    http://localhost:9311/v1/secrets/2a549393-0710-444b-8aa5-84cf0f85ea79

No response will be provided. This is expected behavior! If you do receive a
response, something went wrong and you will have to address that before
moving forward. (For more information visit
`PUT /v1/secrets/{uuid} <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#put-secrets>`__
.)


.. _retrieve_secret:

How to Retrieve a Secret
########################

To retrieve the secret we have created we will need to know the secret reference
provided via the initial creation (See :ref:`How to Create a Secret <create_secret>`.)

.. code-block:: bash

    curl -H "Accept: text/plain" -H "X-Auth-Token: $TOKEN" \
    http://localhost:9311/v1/secrets/2a549393-0710-444b-8aa5-84cf0f85ea79/payload

This should provide a response as follows:

.. code-block:: bash

    my-secret-here

This is the plain text data we provided upon initial creation of the secret.

How to Delete a Secret
######################

To delete a secret we will need to know the secret reference provided via
the initial creation (See :ref:`How to Create a Secret <create_secret>`.)

.. code-block:: bash

    curl -X DELETE -H "X-Auth-Token: $TOKEN" \
    http://localhost:9311/v1/secrets/2a549393-0710-444b-8aa5-84cf0f85ea79

No response will be provided. This is expected behavior! If you do receive a
response, something went wrong and you will have to address that before
moving forward. (For more information visit
`DELETE /v1/secrets/{uuid} <https://docs.openstack.org/barbican/latest/api/reference/secrets.html#delete-secrets>`__
.)