Reference

Client

barbicanclient.client.Client(version=None, session=None, *args, **kwargs)

Barbican client used to interact with barbican service.

Parameters:

  • session – An instance of keystoneauth1.session.Session that can be either authenticated, or not authenticated. When using a non-authenticated Session, you must provide some additional parameters. When no session is provided it will default to a non-authenticated Session. (optional)

  • endpoint – Barbican endpoint url override. Required when a session is not given, or when using a non-authenticated session. When using an authenticated session, the client will attempt to get the endpoint from the Keystone service catalog. (optional)

  • project_id – The project ID used for context in Barbican. Required when a session is not given, or when using a non-authenticated session. When using an authenticated session, the project ID will be provided by the authentication mechanism and this parameter will be ignored. (optional)

  • verify – When a session is not given, the client will create a non-authenticated session. This parameter is passed to the session that is created. If set to False, it allows barbicanclient to perform “insecure” TLS (https) requests. The server’s certificate will not be verified against any certificate authorities. (optional) WARNING: This option should be used with caution.

  • version – Used as an endpoint filter when using an authenticated keystone session. When using a non-authenticated keystone session, this value is appended to the required endpoint url override. Defaults to ‘v1’.

  • service_type – Used as an endpoint filter when using an authenticated keystone session. Defaults to ‘key-manager’.

  • service_name – Used as an endpoint filter when using an authenticated keystone session.

  • interface – Used as an endpoint filter when using an authenticated keystone session. Defaults to ‘public’.

  • region_name – Used as an endpoint filter when using an authenticated keystone session.

  • microversion – Specifiy an API Microversion to be used. Defaults to ‘1.1’.

Secrets

class barbicanclient.v1.secrets.SecretManager(api)

Entity Manager for Secret entities

create(name=None, payload=None, payload_content_type=None, payload_content_encoding=None, algorithm=None, bit_length=None, secret_type=None, mode=None, expiration=None)

Factory method for creating new Secret objects

Secrets returned by this method have not yet been stored in the Barbican service.

Parameters:

  • name – A friendly name for the Secret

  • payload – The unencrypted secret data

  • payload_content_type – DEPRECATED: The format/type of the secret data. Setting this can lead to unexpected results. See Launchpad Bug #1419166.

  • payload_content_encoding – DEPRECATED: The encoding of the secret data. Setting this can lead to unexpected results. See Launchpad Bug #1419166.

  • algorithm – The algorithm associated with this secret key

  • bit_length – The bit length of this secret key

  • mode – The algorithm mode used with this secret key

  • secret_type – The secret type for this secret key

  • expiration – The expiration time of the secret in ISO 8601 format

Returns:

A new Secret object

Return type:

barbicanclient.v1.secrets.Secret

Raises:
delete(secret_ref, force=False)

Delete a Secret from Barbican

Parameters:

  • secret_ref – Full HATEOAS reference to a Secret, or a UUID

  • force – When true, forces the deletion of secrets with consumers

Raises:
get(secret_ref, payload_content_type=None)

Retrieve an existing Secret from Barbican

Parameters:

  • secret_ref (str) – Full HATEOAS reference to a Secret, or a UUID

  • payload_content_type (str) – DEPRECATED: Content type to use for payload decryption. Setting this can lead to unexpected results. See Launchpad Bug #1419166.

Returns:

Secret object retrieved from Barbican

Return type:

barbicanclient.v1.secrets.Secret

Raises:
list(limit=10, offset=0, name=None, algorithm=None, mode=None, bits=0, secret_type=None, created=None, updated=None, expiration=None, sort=None)

List Secrets for the project

This method uses the limit and offset parameters for paging, and also supports filtering.

The time filters (created, updated, and expiration) are expected to be an ISO 8601 formatted string, which can be prefixed with comparison operators: ‘gt:’ (greater-than), ‘gte:’ (greater-than-or-equal), ‘lt:’ (less-than), or ‘lte’: (less-than-or-equal).

Parameters:

  • limit – Max number of secrets returned

  • offset – Offset secrets to begin list

  • name – Name filter for the list

  • algorithm – Algorithm filter for the list

  • mode – Mode filter for the list

  • bits – Bits filter for the list

  • secret_type – Secret type filter for the list

  • created – Created time filter for the list, an ISO 8601 format string, optionally prefixed with ‘gt:’, ‘gte:’, ‘lt:’, or ‘lte:’

  • updated – Updated time filter for the list, an ISO 8601 format string, optionally prefixed with ‘gt:’, ‘gte:’, ‘lt:’, or ‘lte:’

  • expiration – Expiration time filter for the list, an ISO 8601 format string, optionally prefixed with ‘gt:’, ‘gte:’, ‘lt:’, or ‘lte:’

  • sort – Determines the sorted order of the returned list, a string of comma-separated sort keys (‘created’, ‘expiration’, ‘mode’, ‘name’, ‘secret_type’, ‘status’, or ‘updated’) with a direction appended (‘:asc’ or ‘:desc’) to each key

Returns:

list of Secret objects that satisfy the provided filter criteria.

Return type:

list

Raises:
list_consumers(secret_ref, limit=10, offset=0)

List consumers of the secret

Parameters:

  • secret_ref – Full HATEOAS reference to a secret, or a UUID

  • limit – Max number of consumers returned

  • offset – Offset secrets to begin list

Raises:
register_consumer(secret_ref, service, resource_type, resource_id)

Add a consumer to the secret

Parameters:

  • secret_ref – Full HATEOAS reference to a secret, or a UUID

  • service – Name of the consuming service

  • resource_type – Type of the consuming resource

  • resource_id – ID of the consuming resource

Returns:

A secret object per the get() method

Raises:
remove_consumer(secret_ref, service, resource_type, resource_id)

Remove a consumer from the secret

Parameters:

  • secret_ref – Full HATEOAS reference to a secret, or a UUID

  • service – Name of the previously consuming service

  • resource_type – type of the previously consuming resource

  • resource_id – ID of the previously consuming resource

Raises:
update(secret_ref, payload=None)

Update an existing Secret in Barbican

Parameters:

  • secret_ref (str) – Full HATEOAS reference to a Secret, or a UUID

  • payload (str) – New payload to add to secret

Raises:
class barbicanclient.v1.secrets.Secret(api, name=None, expiration=None, algorithm=None, bit_length=None, mode=None, payload=None, payload_content_type=None, payload_content_encoding=None, secret_ref=None, created=None, updated=None, content_types=None, status=None, secret_type=None, creator_id=None, consumers=None)

Secrets managed by Barbican

Secrets represent keys, credentials, and other sensitive data that is stored by the Barbican service.

Secret objects should not be instantiated directly.

You should use the create or get methods of the barbicanclient.secrets.SecretManager instead.

property acls

Get ACL settings for this secret.

delete()

Deletes the Secret from Barbican

property payload

Lazy-loaded property that holds the unencrypted data

store()

Stores the Secret in Barbican.

New Secret objects are not persisted in Barbican until this method is called.

Raises:

PayloadException

update()

Updates the secret in Barbican.

Orders

class barbicanclient.v1.orders.OrderManager(api)

Entity Manager for Order entitites

create_asymmetric(name=None, algorithm=None, bit_length=None, pass_phrase=None, payload_content_type=None, expiration=None)

Factory method for AsymmetricOrder objects

AsymmetricOrder objects returned by this method have not yet been submitted to the Barbican service.

Parameters:

  • name – A friendly name for the container to be created

  • algorithm – The algorithm associated with this secret key

  • bit_length – The bit length of this secret key

  • pass_phrase – Optional passphrase

  • payload_content_type – The format/type of the secret data

  • expiration – The expiration time of the secret in ISO 8601 format

Returns:

AsymmetricOrder

Return type:

barbicanclient.v1.orders.AsymmetricOrder

Raises:
create_certificate(name=None, request_type=None, subject_dn=None, source_container_ref=None, ca_id=None, profile=None, request_data=None)

Factory method for CertificateOrder objects

CertificateOrder objects returned by this method have not yet been submitted to the Barbican service.

Parameters:

  • name – A friendly name for the container to be created

  • request_type – The type of the certificate request

  • subject_dn – A subject for the certificate

  • source_container_ref – A container with a public/private key pair to use as source for stored-key requests

  • ca_id – The identifier of the CA to use

  • profile – The profile of certificate to use

  • request_data – The CSR content

Returns:

CertificateOrder

Return type:

barbicanclient.v1.orders.CertificateOrder

create_key(name=None, algorithm=None, bit_length=None, mode=None, payload_content_type=None, expiration=None)

Factory method for KeyOrder objects

KeyOrder objects returned by this method have not yet been submitted to the Barbican service.

Parameters:

  • name – A friendly name for the secret to be created

  • algorithm – The algorithm associated with this secret key

  • bit_length – The bit length of this secret key

  • mode – The algorithm mode used with this secret key

  • payload_content_type – The format/type of the secret data

  • expiration – The expiration time of the secret in ISO 8601 format

Returns:

KeyOrder

Return type:

barbicanclient.v1.orders.KeyOrder

Raises:
delete(order_ref)

Delete an Order from Barbican

Parameters:

order_ref – Full HATEOAS reference to an Order, or a UUID

get(order_ref)

Retrieve an existing Order from Barbican

Parameters:

order_ref – Full HATEOAS reference to an Order, or a UUID

Returns:

An instance of the appropriate subtype of Order

Raises:
list(limit=10, offset=0)

List Orders for the project

This method uses the limit and offset parameters for paging.

Parameters:

  • limit – Max number of orders returned

  • offset – Offset orders to begin list

Returns:

list of Order objects

Raises:
class barbicanclient.v1.orders.Order(api, type, status=None, created=None, updated=None, meta=None, order_ref=None, error_status_code=None, error_reason=None, sub_status=None, sub_status_message=None, creator_id=None)

Base order object to hold common functionality

This should be considered an abstract class that should not be instantiated directly.

delete()

Deletes the Order from Barbican

submit()

Submit the Order to Barbican.

New Order objects are not persisted in Barbican until this method is called.

class barbicanclient.v1.orders.KeyOrder(api, name=None, algorithm=None, bit_length=None, mode=None, expiration=None, payload_content_type=None, status=None, created=None, updated=None, order_ref=None, secret_ref=None, error_status_code=None, error_reason=None, sub_status=None, sub_status_message=None, creator_id=None)

KeyOrders can be used to request random key material from Barbican

property mode

Encryption mode being used with this key

The mode could be set to “CBC” for example, when requesting a key that will be used for AES encryption in CBC mode.

class barbicanclient.v1.orders.AsymmetricOrder(api, name=None, algorithm=None, bit_length=None, mode=None, passphrase=None, pass_phrase=None, expiration=None, payload_content_type=None, status=None, created=None, updated=None, order_ref=None, container_ref=None, error_status_code=None, error_reason=None, sub_status=None, sub_status_message=None, creator_id=None)
property pass_phrase

Passphrase to be used for passphrase protected asymmetric keys

Containers

class barbicanclient.v1.containers.ContainerManager(api)

EntityManager for Container entities

You should use the ContainerManager exposed by the Client and should not need to instantiate your own.

create(name=None, secrets=None)

Factory method for Container objects

Container objects returned by this method have not yet been stored in Barbican.

Parameters:

  • name – A friendly name for the Container

  • secrets – Secrets to populate when creating a Container

Returns:

Container

Return type:

barbicanclient.v1.containers.Container

Raises:
create_certificate(name=None, certificate=None, intermediates=None, private_key=None, private_key_passphrase=None)

Factory method for CertificateContainer objects

CertificateContainer objects returned by this method have not yet been stored in Barbican.

Parameters:

  • name – A friendly name for the CertificateContainer

  • certificate – Secret object containing a Certificate

  • intermediates – Secret object containing Intermediate Certs

  • private_key – Secret object containing a Private Key

  • private_key_passphrase – Secret object containing a passphrase

Returns:

CertificateContainer

Return type:

barbicanclient.v1.containers.CertificateContainer

Raises:
create_rsa(name=None, public_key=None, private_key=None, private_key_passphrase=None)

Factory method for RSAContainer objects

RSAContainer objects returned by this method have not yet been stored in Barbican.

Parameters:

  • name – A friendly name for the RSAContainer

  • public_key – Secret object containing a Public Key

  • private_key – Secret object containing a Private Key

  • private_key_passphrase – Secret object containing a passphrase

Returns:

RSAContainer

Return type:

barbicanclient.v1.containers.RSAContainer

Raises:
delete(container_ref)

Delete a Container from Barbican

Parameters:

container_ref – Full HATEOAS reference to a Container, or a UUID

Raises:
get(container_ref)

Retrieve an existing Container from Barbican

Parameters:

container_ref – Full HATEOAS reference to a Container, or a UUID

Returns:

Container object or a subclass of the appropriate type

list(limit=10, offset=0, name=None, type=None)

List containers for the project.

This method uses the limit and offset parameters for paging.

Parameters:

  • limit – Max number of containers returned

  • offset – Offset containers to begin list

  • name – Name filter for the list

  • type – Type filter for the list

Returns:

list of Container metadata objects

Raises:
register_consumer(container_ref, name, url)

Add a consumer to the container

Parameters:

  • container_ref – Full HATEOAS reference to a Container, or a UUID

  • name – Name of the consuming service

  • url – URL of the consuming resource

Returns:

A container object per the get() method

Raises:
remove_consumer(container_ref, name, url)

Remove a consumer from the container

Parameters:

  • container_ref – Full HATEOAS reference to a Container, or a UUID

  • name – Name of the previously consuming service

  • url – URL of the previously consuming resource

Raises:
class barbicanclient.v1.containers.Container(api, name=None, secrets=None, consumers=None, container_ref=None, created=None, updated=None, status=None, secret_refs=None)

Container is a generic grouping of Secrets

property acls

Get ACL settings for this container.

delete()

Delete container from Barbican

property secrets

List of Secrets in Containers

store()

Store Container in Barbican

class barbicanclient.v1.containers.RSAContainer(api, name=None, public_key=None, private_key=None, private_key_passphrase=None, consumers=[], container_ref=None, created=None, updated=None, status=None, public_key_ref=None, private_key_ref=None, private_key_passphrase_ref=None)
property private_key

Secret containing the Private Key

property private_key_passphrase

Secret containing the Passphrase

property public_key

Secret containing the Public Key

class barbicanclient.v1.containers.CertificateContainer(api, name=None, certificate=None, intermediates=None, private_key=None, private_key_passphrase=None, consumers=[], container_ref=None, created=None, updated=None, status=None, certificate_ref=None, intermediates_ref=None, private_key_ref=None, private_key_passphrase_ref=None)
property certificate

Secret containing the certificate

property intermediates

Secret containing intermediate certificates

property private_key

Secret containing the private key

property private_key_passphrase

Secret containing the passphrase

Certificate Authorities

class barbicanclient.v1.cas.CAManager(api)

Entity Manager for Secret entities

get(ca_ref)

Retrieve an existing CA from Barbican

Parameters:

ca_ref (str) – Full HATEOAS reference to a CA

Returns:

CA object retrieved from Barbican

Return type:

barbicanclient.v1.cas.CA

Raises:
list(limit=10, offset=0, name=None)

List CAs for the project

This method uses the limit and offset parameters for paging, and also supports filtering.

Parameters:

  • limit – Max number of CAs returned

  • offset – Offset secrets to begin list

  • name – Name filter for the list

Returns:

list of CA objects that satisfy the provided filter criteria.

Return type:

list

Raises:
class barbicanclient.v1.cas.CA(api, meta=None, expiration=None, plugin_name=None, plugin_ca_id=None, ca_ref=None, created=None, updated=None, status=None, creator_id=None)

Certificate authority

CAs represent certificate authorities or subCAs with which the Barbican service is configured to interact.

Certificate authority

CA objects should not be instantiated directly. You should use the create or get methods of the barbicanclient.cas.CAManager instead.

ACLs

class barbicanclient.v1.acls.ACLManager(api)

Entity Manager for Secret or Container ACL entities

create(entity_ref=None, users=None, project_access=None, operation_type='read')

Factory method for creating ACL entity.

ACL object returned by this method have not yet been stored in Barbican.

Input entity_ref is used to determine whether ACL object type needs to be barbicanclient.acls.SecretACL or barbicanclient.acls.ContainerACL.

Parameters:

  • entity_ref (str) – Full HATEOAS reference to a secret or container

  • users (List or None) – List of Keystone userid(s) to be used in ACL.

  • project_access (bool) – Flag indicating project access behavior

  • operation_type (str) – Type indicating which class of Barbican operations this ACL is defined for e.g. ‘read’ operations

Returns:

ACL object instance

Return type:

barbicanclient.v1.acls.SecretACL or barbicanclient.v1.acls.ContainerACL

get(entity_ref)

Retrieve existing ACLs for a secret or container found in Barbican

Parameters:

entity_ref (str) – Full HATEOAS reference to a secret or container.

Returns:

ACL entity object instance

Return type:

barbicanclient.v1.acls.SecretACL or barbicanclient.v1.acls.ContainerACL

Raises:
class barbicanclient.v1.acls.SecretACL(api, entity_ref, users=None, project_access=None, operation_type='read', created=None, updated=None)

ACL entity for a secret

Base ACL entity instance for secret or container.

Provide ACL data arguments to set ACL setting for given operation_type.

To add ACL setting for other operation types, use add_operation_acl method.

Parameters:

  • api – client instance reference

  • entity_ref (str) – Full HATEOAS reference to a secret or container

  • users (str List or None) – List of Keystone userid(s) to be used for ACL.

  • project_access (bool) – Flag indicating project access behavior

  • operation_type (str) – Type indicating which class of Barbican operations this ACL is defined for e.g. ‘read’ operations

  • created (str) – Time string indicating ACL create timestamp. This is populated only when populating data from api response. Not needed in client input.

  • updated (str) – Time string indicating ACL last update timestamp. This is populated only when populating data from api response. Not needed in client input.

add_operation_acl(users=None, project_access=None, operation_type=None, created=None, updated=None)

Add ACL settings to entity for specific operation type.

If matching operation_type ACL already exists, then it replaces it with new PerOperationACL object using provided inputs. Otherwise it appends new PerOperationACL object to existing per operation ACL list.

This just adds to local entity and have not yet applied these changes to server.

Parameters:

  • users (List or None) – List of Keystone userid(s) to be used in ACL.

  • project_access (bool) – Flag indicating project access behavior

  • operation_type (str) – Type indicating which class of Barbican operations this ACL is defined for e.g. ‘read’ operations

  • created (str) – Time string indicating ACL create timestamp. This is populated only when populating data from api response. Not needed in client input.

  • updated (str) – Time string indicating ACL last update timestamp. This is populated only when populating data from api response. Not needed in client input.

property entity_ref

Entity URI reference.

property entity_uuid

Entity UUID

get(operation_type)

Get operation specific ACL instance.

Parameters:

operation_type (str) – Type indicating which operation’s ACL setting is needed.

load_acls_data()

Loads ACL entity from Barbican server using its acl_ref

Clears the existing list of per operation ACL settings if there. Populates current ACL entity with ACL settings received from Barbican server.

Raises:
property operation_acls

List of operation specific ACL settings.

remove()

Remove Barbican ACLs setting defined for a secret or container

Raises:
submit()

Submits ACLs for a secret or a container defined in server

In existing ACL case, this overwrites the existing ACL setting with provided inputs. If input users are None or empty list, this will remove existing ACL users if there. If input project_access flag is None, then default project access behavior is enabled.

Returns:

str acl_ref: Full HATEOAS reference to a secret or container ACL.

Raises:
class barbicanclient.v1.acls.ContainerACL(api, entity_ref, users=None, project_access=None, operation_type='read', created=None, updated=None)

ACL entity for a container

Base ACL entity instance for secret or container.

Provide ACL data arguments to set ACL setting for given operation_type.

To add ACL setting for other operation types, use add_operation_acl method.

Parameters:

  • api – client instance reference

  • entity_ref (str) – Full HATEOAS reference to a secret or container

  • users (str List or None) – List of Keystone userid(s) to be used for ACL.

  • project_access (bool) – Flag indicating project access behavior

  • operation_type (str) – Type indicating which class of Barbican operations this ACL is defined for e.g. ‘read’ operations

  • created (str) – Time string indicating ACL create timestamp. This is populated only when populating data from api response. Not needed in client input.

  • updated (str) – Time string indicating ACL last update timestamp. This is populated only when populating data from api response. Not needed in client input.

add_operation_acl(users=None, project_access=None, operation_type=None, created=None, updated=None)

Add ACL settings to entity for specific operation type.

If matching operation_type ACL already exists, then it replaces it with new PerOperationACL object using provided inputs. Otherwise it appends new PerOperationACL object to existing per operation ACL list.

This just adds to local entity and have not yet applied these changes to server.

Parameters:

  • users (List or None) – List of Keystone userid(s) to be used in ACL.

  • project_access (bool) – Flag indicating project access behavior

  • operation_type (str) – Type indicating which class of Barbican operations this ACL is defined for e.g. ‘read’ operations

  • created (str) – Time string indicating ACL create timestamp. This is populated only when populating data from api response. Not needed in client input.

  • updated (str) – Time string indicating ACL last update timestamp. This is populated only when populating data from api response. Not needed in client input.

property entity_ref

Entity URI reference.

property entity_uuid

Entity UUID

get(operation_type)

Get operation specific ACL instance.

Parameters:

operation_type (str) – Type indicating which operation’s ACL setting is needed.

load_acls_data()

Loads ACL entity from Barbican server using its acl_ref

Clears the existing list of per operation ACL settings if there. Populates current ACL entity with ACL settings received from Barbican server.

Raises:
property operation_acls

List of operation specific ACL settings.

remove()

Remove Barbican ACLs setting defined for a secret or container

Raises:
submit()

Submits ACLs for a secret or a container defined in server

In existing ACL case, this overwrites the existing ACL setting with provided inputs. If input users are None or empty list, this will remove existing ACL users if there. If input project_access flag is None, then default project access behavior is enabled.

Returns:

str acl_ref: Full HATEOAS reference to a secret or container ACL.

Raises:

Exceptions

exception barbicanclient.exceptions.BarbicanException
exception barbicanclient.exceptions.HTTPAuthError(message, status_code=401)

Raised for 401 Unauthorized responses from the server.

exception barbicanclient.exceptions.HTTPClientError(message, status_code=0)

Raised for 4xx responses from the server.

exception barbicanclient.exceptions.HTTPError(message, status_code=0)

Base exception for HTTP errors.

exception barbicanclient.exceptions.HTTPServerError(message, status_code=0)

Raised for 5xx responses from the server.

exception barbicanclient.exceptions.PayloadException
exception barbicanclient.exceptions.UnsupportedVersion

User is trying to use an unsupported version of the API.