Client library for Barbican API.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

usage.rst 11KB

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:

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:

The secret reference returned by barbicanclient.secrets.SecretManager.store can later be used to retrieve the secret data from barbican.

Example:

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:

The order reference returned by barbicanclient.orders.Order.submit can later be used to retrieve the order from Barbican.

Example:

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:

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:

The container reference returned by barbicanclient.containers.Container.store can later be used to retrieve the container from Barbican.

Example:

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:

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:

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:

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:

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:

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: