========
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)