ae77599995
Updated documentation for the client. Added a few methods and properties to the Reference page. Change-Id: Ief022eb7afe3bda90726413dc42bc99fe3826b95
144 lines
4.3 KiB
ReStructuredText
144 lines
4.3 KiB
ReStructuredText
============
|
|
Client 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::
|
|
|
|
# Store a random plain text password in Barbican
|
|
|
|
from barbicanclient import client
|
|
import random
|
|
import string
|
|
|
|
def random_password(length):
|
|
sys_random = random.SystemRandom()
|
|
return u''.join(
|
|
sys_random.choice(string.ascii_letters + string.digits) for _ in range(length)
|
|
)
|
|
|
|
barbican = client.Client(...)
|
|
|
|
my_secret = barbican.secrets.create()
|
|
my_secret.name = u'Random plain text password'
|
|
my_secret.payload = random_password(24)
|
|
my_secret.payload_content_type = u'text/plain'
|
|
|
|
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)
|
|
my_password = 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)
|
|
|