python-barbicanclient/doc/source/usage.rst

Usage

To use barbicanclient, you must first create an instance of the 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 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 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 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 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 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 barbicanclient.orders.KeyOrder orders for Keys suitable for symmetric encryption, and 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 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 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)