Client Usage¶

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:

# Store a random 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_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)
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 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)

ACLs¶

Access Control List (ACL) feature in Barbican provides user level access control for secrets and containers. By default Barbican manages access to its resources (secrets, containers) on a per project level and authorization is granted based on the roles a user has in that project.

ACLs should be managed using the barbicanclient.acls.ACLManager instance in the acls attribute of the Client.

Example:

# Submits ACLs on an existing Secret with URI as 'secret_ref'

# create ACL entity object with needed settings
acl_entity = barbican.acls.create(entity_ref=secret_ref, users=[u1, u2],
                                  project_access=False)

acl_ref = acl_entity.submit()  # submits ACL setting to server at this point.

The secret or container URI can be used to read all of its ACL setting. Returned value is instance of either barbicanclient.acls.SecretACL or barbicanclient.acls.ContainerACL. Refer to respective class for its available APIs.

Example:

# Get ACL entity for a Secret
# Returned entity will be either SecretACL or ContainerACL.
# This entity has ACL settings per operation type (e.g. 'read')

secret_acl = barbican.acls.get(secret_ref)

# To retrieve (load) ACL using existing ACL entity e.g. container_acl
container_acl.load_acls_data()

ACLs setting can also be retrieved directly from secret or container entity. Its data is lazy loaded i.e. related ACL settings are not read till acls attribute is accessed on secret or container entity.

Example:

# Get secret entity for a given ref
secret = barbican.secrets.get(secret_ref)

# To get project access flag or users for 'read' operation
project_access_flag = secret.acls.read.project_access
read_acl_users = secret.acls.read.users


# Get container entity for a given ref
container = barbican.containers.get(container_ref)

# To get project access flag or users for 'read' operation
project_access_flag = container.acls.read.project_access
read_acl_users = container.acls.read.users

If need to add users to existing ‘read’ ACL settings on a secret or container, above mentioned get and submit methods can be used.

Example:

# Every Barbican secret and container has default ACL setting which
# reflects default project access behavior.

# ACL settings is modified via submit operation on ACL entity.

# provide users to be added as list.
add_users = ['user1', 'user2', 'users3']

# Case 1 - Add users to 'read' operation ACL setting
# --------------------------------------------------

# Get ACL entity from server
acl_entity = barbican.acls.get(entity_ref=secret_ref)

# add new users to existing users for 'read' operation
acl_entity.read.users.extend(add_users)
# OR
# acl_entity.get('read').users.extend(add_users)

acl_ref = acl_entity.submit() # here submits ACL changes to server.

# Case 2 - Add same users to ACL settings for each operation type
# ---------------------------------------------------------------

# Get ACL entity from server
acl_entity = barbican.acls.get(entity_ref=secret_ref)

# Go through each operation ACL setting and add users to existing list
for op_acl in acl_entity.operation_acls
    op_acl.users.extend(add_users)

acl_ref = acl_entity.submit() # here submits ACL changes to server.

If need to remove some users from existing ACL settings on a secret or container, similar approach can be used as mentioned above for add example.

Example:

# provide users to be removed as list.
remove_users = ['user1', 'user2', 'users3']

# Case 1 - Remove users from 'read' operation ACL setting
# -------------------------------------------------------

# Get ACL entity from server
acl_entity = barbican.acls.get(entity_ref=container_ref)

existing_users = acl_entity.read.users
# OR
# existing users = acl_entity.get('read').users

# remove matching users from existing users list
updated_users = set(existing_users).difference(remove_users)

# set back updated users to operation specific acl setting
acl_entity.read.users = updated_users
# OR
# acl_entity.get('read').users = updated_users

acl_ref = acl_entity.submit() # here submits ACL changes to server.

# Case 2 - Remove same users from ACL settings for each operation type
# --------------------------------------------------------------------

# Get ACL entity from server
acl_entity = barbican.acls.get(secret_ref)

# Go through each operation ACL setting and remove users from existing list
for op_acl in acl_entity.operation_acls
    existing_users = op_acl.users

    # remove matching users from existing users list
    updated_users = set(existing_users).difference(remove_users)

    # set back updated users to operation specific acl setting
    op_acl.users = updated_users

acl_ref = acl_entity.submit() # here submits ACL changes to server.

If need to unset or delete ACL settings on a secret or container, barbicanclient.acls.SecretACL.remove() or barbicanclient.acls.ContainerACL.remove() can be used.

Example:

# create ACL entity object with secret or container ref
blank_acl_entity = barbican.acls.create(entity_ref=secret_ref)

# removes all ACL settings for the secret on server
blank_acl_entity.remove()

# To remove 'read' operation specific ACL setting
acl_entity = barbican.acls.get(entity_ref=secret_ref)
acl_entity.read.remove()
# OR
# acl_entity.get('read').remove()