4d31b8bd80
Added Usage and Reference documentation. Change-Id: I37469addf1d44db23ca04302cd5f7ca96c01b5e0
139 lines
4.1 KiB
ReStructuredText
139 lines
4.1 KiB
ReStructuredText
========
|
|
Usage
|
|
========
|
|
|
|
To use barbicanclient, you must first create an instance of the
|
|
:class:`barbicanclient.client.Client` class.
|
|
|
|
The client uses Keystone Sessions for both authentication and for handling HTTP
|
|
requests. You can provide authentication credentials to the client by creating
|
|
a Keystone Session with the appropriate auth plugin and then passing that
|
|
session to the new Client.
|
|
|
|
See :doc:`authentication` for more details.
|
|
|
|
Example::
|
|
|
|
from barbicanclient import client
|
|
|
|
barbican = client.Client(...)
|
|
|
|
The client object has different attributes that can be used to interact with
|
|
the Barbican service. Each attribute represents an entity in the Barbican
|
|
service: Secrets, Orders and Containers.
|
|
|
|
Secrets
|
|
=======
|
|
|
|
Secrets represent keys, credentials, and other sensitive data that is stored
|
|
by the Barbican service. To store or retrieve a secret in the Barbican
|
|
service you should use the different methods of the :class:`barbicanclient.secrets.SecretManager`
|
|
class that is exposed as the `secrets` attribute of the Client.
|
|
|
|
Example::
|
|
|
|
# Create a random encryption key and store it in Barbican
|
|
|
|
import base64
|
|
import os
|
|
from barbicanclient import client
|
|
|
|
barbican = client.Client(...)
|
|
|
|
my_secret = barbican.secrets.create()
|
|
my_secret.name = 'Encryption Key'
|
|
my_secret.payload = base64.b64encode(os.urandom(32))
|
|
my_secret.payload_content_type = 'application/octet-stream'
|
|
my_secret.payload_content_encoding = 'base64'
|
|
|
|
my_secret_ref = my_secret.store()
|
|
|
|
The secret reference returned by :meth:`barbicanclient.secrets.SecretManager.store`
|
|
can later be used to retrieve the secret data from barbican.
|
|
|
|
Example::
|
|
|
|
# Retrieve Secret from secret reference
|
|
|
|
retrieved_secret = barbican.secrets.get(my_secret_ref)
|
|
key = retrieved_secret.payload
|
|
|
|
Orders
|
|
======
|
|
|
|
Orders are used to request secret material to be created by the Barbican
|
|
service. Submitting an order will result in a Secret being created on your
|
|
behalf. The Secret can then be used like any Secret you may have uploaded
|
|
yourself. Orders should be created using the factory methods in the
|
|
:class:`barbicanclient.orders.OrderManager` instance in the `orders`
|
|
attribute of the `Client`.
|
|
|
|
Example::
|
|
|
|
# Submit an order to generate a random encryption key
|
|
|
|
from barbicanclient import client
|
|
|
|
barbican = client.Client(...)
|
|
|
|
my_order = barbican.orders.key_order()
|
|
my_order.algorithm = 'AES'
|
|
my_order.mode = 'CBC'
|
|
my_order.bit_length = 256
|
|
|
|
my_order_ref = my_order.submit()
|
|
|
|
The order reference returned by :meth:`barbicanclient.orders.Order.submit()`
|
|
can later be used to retrieve the order from Barbican.
|
|
|
|
Example::
|
|
|
|
# Retrieve Order from order reference
|
|
|
|
retrieved_order = barbican.orders.get(my_order_ref)
|
|
|
|
Once your order has been processed by Barbican, the order status will be set
|
|
to `'ACTIVE'`. An active order will contain the reference to the requested
|
|
secret (or container).
|
|
|
|
Example::
|
|
|
|
# Retrieve Encryption Key generated by the above KeyOrder
|
|
|
|
generated_secret = barbican.secrets.get(retrieved_order.secret_ref)
|
|
key = generated_secret.payload
|
|
|
|
Currently the client can submit :class:`barbicanclient.orders.KeyOrder` orders
|
|
for Keys suitable for symmetric encryption, and :class:`barbicanclient.orders.AsymmetricOrder`
|
|
for Asymmetric keys such as RSA keys.
|
|
|
|
Containers
|
|
==========
|
|
|
|
Containers can be either arbitrary groupings of `Secrets` or a strict
|
|
grouping of Secrets, such as the Public and Private keys of an RSA keypair.
|
|
|
|
Containers should be managed using the :class:`barbicanclient.containers.ContainerManager`
|
|
instance in the `containers` attribute of the `Client`
|
|
|
|
Example::
|
|
|
|
# Add the Secrets created above to a container
|
|
|
|
my_container = barbican.containers.create()
|
|
|
|
my_container.add('Retrieved Secret', retrieved_secret)
|
|
my_container.add('Generated Secret', generated_secret)
|
|
|
|
my_container_ref = my_container.store()
|
|
|
|
The container reference returned by :meth:`barbicanclient.containers.Container.store`
|
|
can later be used to retrieve the container from Barbican.
|
|
|
|
Example::
|
|
|
|
# Retrieve container from Barbican
|
|
|
|
retrieved_container = barbican.containers.get(my_container_ref)
|
|
|