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.
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.
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, responses, and status codes you can reference the secret reference documentation.
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 section.
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:
{"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 How to Retrieve a Secret to make sure our secret is stored as expected.
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.
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:
{"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.
To update the secret data we will need to know the secret reference provided via the initial creation. (See Two Step Secret Creation 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.
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} .)
To retrieve the secret we have created we will need to know the secret reference provided via the initial creation (See How to Create a Secret.)
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:
my-secret-here
This is the plain text data we provided upon initial creation of the secret.
To delete a secret we will need to know the secret reference provided via the initial creation (See How to Create a Secret.)
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} .)
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.