Client Usage

The python bindings for the barbican client are designed to ease integration with barbican by abstracting away the ReST API and allowing the user to consume objects.

Configuration

To configure the client, barbicanclient/etc/barbicanclient.conf should be copied to the home directory, and that version should be used to make any desired changes.

Connection

A Connection is used to create, list, and manage secrets and orders.

from barbicanclient import client

identity = 'https://my-keystone-instance'
username = 'my_username'
password = 'my_password'
tenant_id = 'keystone_tenant_id'
endpoint = 'http://path/to/keystone'
conn = client.Connection(identity, username, password, tenant_id, endpoint=endpoint)

Secrets

Create

conn.create_secret(mime_type,
                   plain_text,
                   name,
                   algorithm,
                   bit_length,
                   cypher_type,
                   expiration)

mime_type is the only required field.

• mime_type - The MIME type of the secret. This will be used to fetch the secret back out.
• plain_text - The unencrypted secret.
• name - A friendly name for the secret. This is metadata and only for reference.
• algorithm - The algorithm the secret is used with. This is metadata and only for reference.
• bit_length - The bit length of the secret. This is metadata and only for reference.
• cypher_type - The cypher type (e.g. block cipher mode of operation). This is metadata and only for reference.
• expiration - Optional expiration time for the secret. Must be in ISO 8601 format (e.g. 2012-11-05T13:15:30Z). After a secret has expired you will be unable to read it.

create_secret() returns a Secret object with all of its metadata filled in.

Read

Barbican separates secret metadata from the secret payload itself. To obtain the metadata as a Secret object:

my_secret_id = 'some-uuid'
secret_metadata = conn.get_secret_by_id(my_secret_id)
# or you can get it by href
my_secret_href = 'http://localhost:9392/v1/1234/secrets/742f2e9a-834c-49fd-a843-80342d32c8a1'
secret_metadata = conn.get_secret(my_secret_href)

To obtain the raw secret (secret payload):

my_secret_id = 'some-uuid'
my_secret_mime = 'text/plain'
secret_metadata = conn.get_raw_secret_by_id(my_secret_id, my_secret_mime)
# or you can get it by href
my_secret_href = 'http://localhost:9392/v1/1234/secrets/742f2e9a-834c-49fd-a843-80342d32c8a1'
secret_metadata = conn.get_raw_secret(my_secret_href, my_secret_mime)

List

conn.list_secrets(limit=10,
                  offset=0)

• limit - The limit to the number of secrets to be listed.
• offset - The number of places from the beginning to start listing.

conn.list_secrets_by_href(href)

• href - The full secrets URI

By default, the list_secrets method returns a maximum of 10 secrets with offset 0 along with previous and next references, which can be used to fetch different pages.

A limit of 5 is used in the example below.

secret_list, prev_ref, next_ref = conn.list_secrets(5)

more_secrets, prev_ref, next_ref = conn.list_secrets_by_href(next_ref)

more_secrets contains the 5 secrets after those in secret_list.

Delete

my_secret_id = 'some-uuid'
conn.delete_secret_by_id(my_secret_id)
# or you can do it by href
my_secret_href = 'http://localhost:9392/v1/1234/secrets/742f2e9a-834c-49fd-a843-80342d32c8a1'
conn.delete_secret(my_secret_href)

Deletion does not have a return value but will raise an exception if an error occurs.

Orders

Create

conn.create_order(mime_type,
                  name,
                  algorithm,
                  bit_length,
                  cypher_type)

• mime_type - The MIME type of the secret. This will be used to fetch the secret back out.
• name - A friendly name for the secret. This is metadata and only for reference.
• algorithm - The algorithm the secret is used with. This is metadata and only for reference.
• bit_length - The bit length of the secret. This is metadata and only for reference.
• cypher_type - The cypher type (e.g. block cipher mode of operation). This is metadata and only for reference.

create_order()returns an Order object with all of its metadata filled in.

Read

Getting the Order:

my_order_id = 'some-uuid'
order = conn.get_order_by_id(my_secret_id)
# or you can get it by href
my_order_href = 'http://localhost:9392/v1/1234/orders/742f2e9a-834c-49fd-a843-80342d32c8a1'
order = conn.get_order(my_secret_href)

Getting the Secret associated with an Order object:

secret = order.get_secret()

List

conn.list_orders(limit=10,
                 offset=0)

• limit - The limit to the number of orders to be listed.
• offset - The number of places from the beginning to start listing.

conn.list_orders_by_href(href)

• href - The full orders URI

By default, the list_orders method returns a maximum of 10 orders with offset 0 along with previous and next references, which can be used to fetch different pages.

A limit of 5 is used in the example below.

order_list, prev_ref, next_ref = conn.list_orders(5)

more_orders, prev_ref, next_ref = conn.list_orders_by_href(next_ref)

more_orders contains the 5 orders after those in order_list.

Delete

my_secret_id = 'some-uuid'
conn.delete_order_by_id(my_secret_id)
# or you can do it by href
my_secret_href = 'http://localhost:9392/v1/1234/orders/742f2e9a-834c-49fd-a843-80342d32c8a1'
conn.delete_order(my_secret_href)

Deletion does not have a return value but will raise an exception if an error occurs.