325 lines
10 KiB
ReStructuredText
325 lines
10 KiB
ReStructuredText
****************************
|
|
Containers API - User Guide
|
|
****************************
|
|
|
|
The containers resource is the organizational center piece of barbican. It
|
|
creates a logical object that can be used to hold secret references. This is helpful
|
|
when having to deal with tracking and having access to hundreds of secrets.
|
|
|
|
Barbican supports 3 types of containers:
|
|
* :ref:`Generic <generic_containers>`
|
|
* :ref:`Certificate <certificate_containers>`
|
|
* :ref:`RSA <rsa_containers>`
|
|
|
|
Each of these types have explicit restrictions as to what type of secrets should be
|
|
held within. These will be broken down in their respective sections.
|
|
|
|
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>`__.
|
|
|
|
.. _generic_containers:
|
|
|
|
Generic Containers
|
|
##################
|
|
|
|
A generic container is used for any type of container that a user may wish to create.
|
|
There are no restrictions on the type or amount of secrets that can be held within a container.
|
|
|
|
An example of a use case for a generic container would be having multiple passwords stored
|
|
in the same container reference:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"type": "generic",
|
|
"status": "ACTIVE",
|
|
"name": "Test Environment User Passwords",
|
|
"consumers": [],
|
|
"container_ref": "https://{barbican_host}/v1/containers/{uuid}",
|
|
"secret_refs": [
|
|
{
|
|
"name": "test_admin_user",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "test_audit_user",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
}
|
|
],
|
|
"created": "2015-03-30T21:10:45.417835",
|
|
"updated": "2015-03-30T21:10:45.417835"
|
|
}
|
|
|
|
For more information on creating a generic container, reference the
|
|
:ref:`Creating a Generic Container <create_generic_container>` section.
|
|
|
|
|
|
.. _certificate_containers:
|
|
|
|
Certificate Containers
|
|
######################
|
|
|
|
A certificate container is used for storing the following secrets that are relevant to
|
|
certificates:
|
|
|
|
* certificate
|
|
* private_key (optional)
|
|
* private_key_passphrase (optional)
|
|
* intermediates (optional)
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"type": "certificate",
|
|
"status": "ACTIVE",
|
|
"name": "Example.com Certificates",
|
|
"consumers": [],
|
|
"container_ref": "https://{barbican_host}/v1/containers/{uuid}",
|
|
"secret_refs": [
|
|
{
|
|
"name": "certificate",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "private_key",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "private_key_passphrase",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "intermediates",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
}
|
|
|
|
],
|
|
"created": "2015-03-30T21:10:45.417835",
|
|
"updated": "2015-03-30T21:10:45.417835"
|
|
}
|
|
|
|
The payload for the secret referenced as the "certificate" is expected to be a
|
|
PEM formatted x509 certificate.
|
|
|
|
The payload for the secret referenced as the "intermediates" is expected to be a
|
|
PEM formatted PKCS7 certificate chain.
|
|
|
|
For more information on creating a certificate container, reference the
|
|
:ref:`Creating a Certificate Container <create_certificate_container>` section.
|
|
|
|
.. _rsa_containers:
|
|
|
|
RSA Containers
|
|
##############
|
|
|
|
An RSA container is used for storing RSA public keys, private keys, and private
|
|
key pass phrases.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"type": "rsa",
|
|
"status": "ACTIVE",
|
|
"name": "John Smith RSA",
|
|
"consumers": [],
|
|
"container_ref": "https://{barbican_host}/v1/containers/{uuid}",
|
|
"secret_refs": [
|
|
{
|
|
"name": "private_key",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "private_key_passphrase",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
},
|
|
{
|
|
"name": "public_key",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{uuid}"
|
|
}
|
|
|
|
],
|
|
"created": "2015-03-30T21:10:45.417835",
|
|
"updated": "2015-03-30T21:10:45.417835"
|
|
}
|
|
|
|
For more information on creating a certificate container, reference the
|
|
:ref:`Creating a RSA Container <create_certificate_container>` section.
|
|
|
|
.. _create_container:
|
|
|
|
How to Create a Container
|
|
#########################
|
|
|
|
In order to create a container, we must first have secrets. If you are unfamiliar
|
|
with creating secrets, please take some time to refer to the
|
|
:doc:`Secret User Guide <secrets>` before moving forward.
|
|
|
|
.. _create_generic_container:
|
|
|
|
Creating a Generic Container
|
|
****************************
|
|
|
|
To create a generic container we must have a secret to store as well.
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-Type:application/json" -d '{
|
|
"type": "generic",
|
|
"name": "generic name",
|
|
"secret_refs": [
|
|
{
|
|
"name": "a secret",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/feac9896-49e9-49e0-9484-1a6153c9498b"
|
|
}
|
|
]
|
|
}' http://localhost:9311/v1/containers
|
|
|
|
This should provide a response as follows:
|
|
|
|
.. code-block:: bash
|
|
|
|
{"container_ref": "http://localhost:9311/v1/containers/0fecaec4-7cd7-4e70-a760-cc7eaf5c3afb"}
|
|
|
|
This is our container reference. We will need this in order to retrieve the container.
|
|
Jump ahead to :ref:`How To Retrieve a Container <retrieve_container>` to make sure our
|
|
container stored as expected.
|
|
|
|
.. _create_certificate_container:
|
|
|
|
Creating a Certificate Container
|
|
********************************
|
|
|
|
To create a certificate container we must have a secret to store as well. As we mentioned
|
|
in :ref:`Certificate Containers section <certificate_containers>` you are required
|
|
to provide a secret named certificate but may also include the optional secrets
|
|
named private_key, private_key_passphrase, and intermediates.
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-Type:application/json" -d '{
|
|
"type": "certificate",
|
|
"name": "certificate container",
|
|
"secret_refs": [
|
|
{
|
|
"name": "certificate",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/f91b84ac-fb19-416b-87dc-e7e41b7f6039"
|
|
},
|
|
{
|
|
"name": "private_key",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/feac9896-49e9-49e0-9484-1a6153c9498b"
|
|
},
|
|
{
|
|
"name": "private_key_passphrase",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/f1106c5b-0347-4197-8947-d9e392bf74a3"
|
|
},
|
|
{
|
|
"name": "intermediates",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/2e86c661-28e8-46f1-8e91-f1d95062695d"
|
|
}
|
|
]
|
|
}' http://localhost:9311/v1/containers
|
|
|
|
This should provide a response as follows:
|
|
|
|
.. code-block:: bash
|
|
|
|
{"container_ref": "http://localhost:9311/v1/containers/0fecaec4-7cd7-4e70-a760-cc7eaf5c3afb"}
|
|
|
|
This is our container reference. We will need this in order to retrieve the container.
|
|
Jump ahead to :ref:`How To Retrieve a Container <retrieve_container>` to make sure our
|
|
container stored as expected.
|
|
|
|
|
|
.. _create_rsa_container:
|
|
|
|
Creating an RSA Container
|
|
*************************
|
|
|
|
To create a certificate container we must have a secret to store as well. As we mentioned
|
|
in :ref:`RSA Containers section <rsa_containers>` you are required
|
|
to provide a secret named public_key, private_key, and private_key_passphrase.
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X POST -H "X-Auth-Token: $TOKEN" -H "Content-Type:application/json" -d '{
|
|
"type": "rsa",
|
|
"name": "rsa container",
|
|
"secret_refs": [
|
|
{
|
|
"name": "public_key",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/f91b84ac-fb19-416b-87dc-e7e41b7f6039"
|
|
},
|
|
{
|
|
"name": "private_key",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/feac9896-49e9-49e0-9484-1a6153c9498b"
|
|
},
|
|
{
|
|
"name": "private_key_passphrase",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/f1106c5b-0347-4197-8947-d9e392bf74a3"
|
|
}
|
|
]
|
|
}' http://localhost:9311/v1/containers
|
|
|
|
This should provide a response as follows:
|
|
|
|
.. code-block:: bash
|
|
|
|
{"container_ref": "http://localhost:9311/v1/containers/0fecaec4-7cd7-4e70-a760-cc7eaf5c3afb"}
|
|
|
|
This is our container reference. We will need this in order to retrieve the container.
|
|
Jump ahead to :ref:`How To Retrieve a Container <retrieve_container>` to make sure our
|
|
container stored as expected.
|
|
|
|
.. _retrieve_container:
|
|
|
|
How to Retrieve a Container
|
|
###########################
|
|
|
|
To retrieve a container we must have a container reference.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X GET -H "X-Auth-Token: $TOKEN" http://localhost:9311/v1/containers/49d3c5e9-80bb-47ec-8787-968bb500d76e
|
|
|
|
This should provide a response as follows:
|
|
|
|
.. code-block:: bash
|
|
|
|
{
|
|
"status": "ACTIVE",
|
|
"updated": "2015-03-31T21:21:34.126042",
|
|
"name": "container name",
|
|
"consumers": [],
|
|
"created": "2015-03-31T21:21:34.126042",
|
|
"container_ref": "http://localhost:9311/v1/containers/49d3c5e9-80bb-47ec-8787-968bb500d76e",
|
|
"secret_refs": [
|
|
{
|
|
"secret_ref": "http://localhost:9311/v1/secrets/feac9896-49e9-49e0-9484-1a6153c9498b",
|
|
"name": "a secret"
|
|
}
|
|
],
|
|
"type": "generic"
|
|
}
|
|
|
|
This is the metadata as well as the list of secret references that are stored within the container.
|
|
|
|
|
|
.. _delete_container:
|
|
|
|
How to Delete a Container
|
|
#########################
|
|
|
|
To delete a container we must have a container reference.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X DELETE -H "X-Auth-Token: $TOKEN" http://localhost:9311/v1/containers/d1c23e06-476b-4684-be9f-8afbef42768d
|
|
|
|
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.
|