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.
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, responses, and status codes you can reference the secret reference documentation.
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 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.
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.
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.
How to Update a Secret¶
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} .)
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 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.
How to Delete a 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} .)
