11 KiB
Client 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 = client.Client(...) barbican
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:
# Store a random text password in Barbican from barbicanclient import client import random import string def random_password(length): = random.SystemRandom() sys_random return u''.join( + string.digits) for _ in range(length) sys_random.choice(string.ascii_letters ) = client.Client(...) barbican = barbican.secrets.create() my_secret = u'Random plain text password' my_secret.name = random_password(24) my_secret.payload = my_secret.store() my_secret_ref
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 = barbican.secrets.get(my_secret_ref) retrieved_secret = retrieved_secret.payload my_password
Secret Content Types
The Barbican service defines a Secret Content Type. The client will choose the correct Content Type based on the type of the data that is set on the Secret.payload property. The following table summarizes the mapping of Python types to Barbican Secret Content Types:
six Type | Python 2 Type | Python 3 Type | Barbican Content Type |
---|---|---|---|
six.binary_type | str | bytes | application/octet-stream |
six.text_type | unicode | str | text/plain |
Warning
Previous versions of python-barbicanclient allowed the user to set the payload_content_type and payload_content_encoding properties for any secret. This can lead to unexpected behavior such as changing a unicode string back to a byte string in Python 2, and dropping the base64 encoding of a binary secret as in Launchpad Bug #1419166. Because of this, manually setting the payload_content_type and the payload_content_encoding has been deprecated.
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 = client.Client(...) barbican = barbican.orders.create_key() my_order = 'AES' my_order.algorithm = 'CBC' my_order.mode = 256 my_order.bit_length = my_order.submit() my_order_ref
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 = barbican.orders.get(my_order_ref) retrieved_order
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 = barbican.secrets.get(retrieved_order.secret_ref) generated_secret = generated_secret.payload key
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 = barbican.containers.create() my_container 'Retrieved Secret', retrieved_secret) my_container.add('Generated Secret', generated_secret) my_container.add( = my_container.store() my_container_ref
The container reference returned by barbicanclient.containers.Container.store
can later
be used to retrieve the container from Barbican.
Example:
# Retrieve container from Barbican = barbican.containers.get(my_container_ref) retrieved_container
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 = barbican.acls.create(entity_ref=secret_ref, users=[u1, u2], acl_entity =False) project_access = acl_entity.submit() # submits ACL setting to server at this point. acl_ref
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') = barbican.acls.get(secret_ref) secret_acl # 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 = barbican.secrets.get(secret_ref) secret # To get project access flag or users for 'read' operation = secret.acls.read.project_access project_access_flag = secret.acls.read.users read_acl_users # Get container entity for a given ref = barbican.containers.get(container_ref) container # To get project access flag or users for 'read' operation = container.acls.read.project_access project_access_flag = container.acls.read.users read_acl_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. = ['user1', 'user2', 'users3'] add_users # Case 1 - Add users to 'read' operation ACL setting # -------------------------------------------------- # Get ACL entity from server = barbican.acls.get(entity_ref=secret_ref) acl_entity # 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_entity.submit() # here submits ACL changes to server. acl_ref # Case 2 - Add same users to ACL settings for each operation type # --------------------------------------------------------------- # Get ACL entity from server = barbican.acls.get(entity_ref=secret_ref) acl_entity # 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_entity.submit() # here submits ACL changes to server. acl_ref
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. = ['user1', 'user2', 'users3'] remove_users # Case 1 - Remove users from 'read' operation ACL setting # ------------------------------------------------------- # Get ACL entity from server = barbican.acls.get(entity_ref=container_ref) acl_entity = acl_entity.read.users existing_users # OR # existing users = acl_entity.get('read').users # remove matching users from existing users list = set(existing_users).difference(remove_users) updated_users # set back updated users to operation specific acl setting = updated_users acl_entity.read.users # OR # acl_entity.get('read').users = updated_users = acl_entity.submit() # here submits ACL changes to server. acl_ref # Case 2 - Remove same users from ACL settings for each operation type # -------------------------------------------------------------------- # Get ACL entity from server = barbican.acls.get(secret_ref) acl_entity # Go through each operation ACL setting and remove users from existing list for op_acl in acl_entity.operation_acls = op_acl.users existing_users # remove matching users from existing users list = set(existing_users).difference(remove_users) updated_users # set back updated users to operation specific acl setting = updated_users op_acl.users = acl_entity.submit() # here submits ACL changes to server. acl_ref
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 = barbican.acls.create(entity_ref=secret_ref) blank_acl_entity # removes all ACL settings for the secret on server blank_acl_entity.remove() # To remove 'read' operation specific ACL setting = barbican.acls.get(entity_ref=secret_ref) acl_entity acl_entity.read.remove()# OR # acl_entity.get('read').remove()