PYTHON-BARBICANCLIENT(1)
✨ NAME ✨
python-barbicanclient(1) — python-barbicanclient 7.6.0, bestie. This is the client for the OpenStack Key Management API (Barbican). There’s a Python API (the barbicanclient module) and a command-line interface (installed as barbican).
Contents: everything below, no skips, no cap.
🧚 INSTALLATION 🧚
At the command line, run:
$ pip install python-barbicanclientOr, if you have virtualenvwrapper installed:
$ mkvirtualenv python-barbicanclient
$ pip install python-barbicanclient🌈 USER DOCUMENTATION 🌈
💻 CLI Usage 💻
usage: barbican [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]
[--no-auth] [--os-identity-api-version <identity-api-version>]
[--os-auth-url <auth-url>] [--os-username <auth-user-name>]
[--os-user-id <auth-user-id>] [--os-password <auth-password>]
[--os-user-domain-id <auth-user-domain-id>]
[--os-user-domain-name <auth-user-domain-name>]
[--os-tenant-name <auth-tenant-name>]
[--os-tenant-id <tenant-id>]
[--os-project-id <auth-project-id>]
[--os-project-name <auth-project-name>]
[--os-project-domain-id <auth-project-domain-id>]
[--os-project-domain-name <auth-project-domain-name>]
[--os-auth-token <auth-token>]
[--endpoint <barbican-url>] [--insecure]
[--os-cacert <ca-certificate>] [--os-cert <certificate>]
[--os-key <key>] [--timeout <seconds>]Okay so the examples below assume your credentials are already saved to your environment. If you don’t have variables saved to your environment, or you wanna use different credentials than the ones defined, any of the optional arguments listed above may be passed to Barbican. Flexible, iconic, we love that.
Barbican takes a positional argument <entity>, which specifies whether you wish to operate on a secret or an order. That’s your main character selector, basically.
🔐 Secrets 🔐
$ barbican secret <action>A subcommand describing the action to be performed should follow. The subcommands are mostly the same for secrets and orders, although some optional arguments only apply to one or the other.
Subcommand actions that a user can take for secrets are:
secret consumer— allow operations with secret consumers.secret delete— delete a secret by providing its URI.secret get— retrieve a secret by providing its URI.secret list— list secrets.secret store— store a secret in Barbican.
Each subcommand takes in a different set of arguments, and the help message varies from one to another. The help message for get can be seen below. iykyk, every subcommand has its own little lore.
$ barbican help secret get
usage: barbican secret get [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--fit-width]
[--print-empty] [--noindent] [--prefix PREFIX]
[--decrypt | --payload | --file <filename>]
[--payload_content_type PAYLOAD_CONTENT_TYPE]
URI
Retrieve a secret by providing its URI.
positional arguments:
URI The URI reference for the secret.
optional arguments:
-h, --help show this help message and exit
--decrypt, -d if specified, retrieve the unencrypted secret data.
--payload, -p if specified, retrieve the unencrypted secret data.
--file <filename>, -F <filename>
if specified, save the payload to a new file with the
given filename.
--payload_content_type PAYLOAD_CONTENT_TYPE, -t PAYLOAD_CONTENT_TYPE
the content type of the decrypted secret (default:
text/plain).
output formatters:
output formatter options
-f {shell,table,value}, --format {shell,table,value}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated
table formatter:
--max-width <integer>
Maximum display width, 0 to disable
shell formatter:
a format a UNIX shell can parse (variable="value")
--prefix PREFIX add a prefix to all variable names🎀 Secret Create 🎀
$ barbican secret store -n mysecretname -p 'my secret value'
+---------------+-----------------------------------------------------------------------+
| Field | Value |
+---------------+-----------------------------------------------------------------------+
| Secret href | http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e |
| Name | mysecretname |
| Created | None |
| Status | None |
| Content types | None |
| Algorithm | aes |
| Bit length | 256 |
| Mode | cbc |
| Expiration | None |
+---------------+-----------------------------------------------------------------------+Not trying to put the secret value directly in your command line? Valid. Instead of using the -p or --payload option with the value of the secret in the command line, the value of the secret may be stored in a file. For this method the -F <filename> or --file <filename> option can be used. File-based glow-up, honestly.
🕵️ Secret Get 🕵️
$ barbican secret get http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e
+---------------+-----------------------------------------------------------------------+
| Field | Value |
+---------------+-----------------------------------------------------------------------+
| Secret href | http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e |
| Name | mysecretname |
| Created | 2015-04-16 20:36:40.334696+00:00 |
| Status | ACTIVE |
| Content types | {'default': 'application/octet-stream'} |
| Algorithm | aes |
| Bit length | 256 |
| Mode | cbc |
| Expiration | None |
+---------------+-----------------------------------------------------------------------+To retrieve only the raw value of the payload we have introduced the -p or --payload option paired with the -f value cliff formatting option. (The --decrypt option will perform the same action; however, it will be deprecated.) Heads up, bestie: deprecated means don’t get too attached.
$ barbican secret get http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e --payload -f value
my secret valueInstead of using the -p or --payload option with the value of the secret returned to stdout, the value of the secret may be written to a file. For this method the -F <filename> or --file <filename> option can be used. Lowkey the tidy way to do it.
💀 Secret Delete 💀
If a secret to be deleted has at least one consumer, the secret can only be deleted after removing all consumers, or by using the --force parameter. No skipping the consumer cleanup unless you’re bringing --force to the group chat.
$ barbican secret delete http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e
$ barbican secret delete http://localhost:9311/v1/secrets/0207414d-c23b-47f6-9cef-f44e907ac7a8
Secret has consumers! Remove them first or use the force parameter to delete it.
$ barbican secret delete --force http://localhost:9311/v1/secrets/0207414d-c23b-47f6-9cef-f44e907ac7a8✏️ Secret Update ✏️
$ barbican secret update http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e ``my_payload``In order for a secret to be updated it must have been created without a payload. my_payload will be added as the secret’s payload. So this is specifically for the no-payload-at-creation girlies.
📋 Secret List 📋
$ barbican secret list
+-----------------------------------------------------------------------+------+----------------------------------+--------+-----------------------------------------+-----------+------------+------+------------+
| Secret href | Name | Created | Status | Content types | Algorithm | Bit length | Mode | Expiration |
+-----------------------------------------------------------------------+------+----------------------------------+--------+-----------------------------------------+-----------+------------+------+------------+
| http://localhost:9311/v1/secrets/bb3d8c20-8ea5-4bfc-9645-c8da79c8b371 | None | 2015-04-15 20:37:37.501475+00:00 | ACTIVE | {'default': 'application/octet-stream'} | aes | 256 | cbc | None |
+-----------------------------------------------------------------------+------+----------------------------------+--------+-----------------------------------------+-----------+------------+------+------------+👥 Secret Consumers 👥
$ barbican secret consumer <action>A subcommand describing the action to be performed should follow. The subcommands are mostly the same as for container consumers, although some optional arguments might not apply. Same vibe, slightly different little details.
For all subcommands, the secret URI must be specified. Subcommand actions that a user can take for secret consumers are:
secret consumer create— create a secret consumer.secret consumer delete— delete a secret consumer.secret consumer list— list consumers of a secret.
The help message for list can be seen below.
$ barbican help secret consumer list
usage: barbican secret consumer list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--quote {all,minimal,none,nonnumeric}] [--noindent]
[--max-width <integer>] [--fit-width] [--print-empty]
[--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending] [--limit LIMIT]
[--offset OFFSET]
URIList consumers of a secret.
positional arguments:
URI— the URI reference for the secret, bestie, that's how we find it 💅
optional arguments:
-h,--help— shows this help message and dips, classic--limit LIMIT,-l LIMIT— how many items per page you want to see (default: 10; maximum: 100, so don't get greedy 🍓)--offset OFFSET,-o OFFSET— which page to jump to (default: 0, aka the beginning)
output formatters:
output formatter options, the glow-up for your terminal ✨
-f {csv,json,table,value,yaml},--format {csv,json,table,value,yaml}— picks the output format, defaults totableand honestly the table is giving organized queen energy 👑-c COLUMN,--column COLUMN— picks which column(s) to show, repeat it to stack multiple columns, no cap--sort-column SORT_COLUMN— picks the column(s) to sort by (first column listed wins the priority, and columns that don't exist just get ignored, they're not invited to the party), repeatable--sort-ascending— sorts the column(s) in ascending order, going up like your grades after this manpage 🦋--sort-descending— sorts the column(s) in descending order, coming back down
CSV Formatter:
--quote {all,minimal,none,nonnumeric}— when to wrap stuff in quotes, defaults tononnumericfr fr
json formatter:
--noindent— disables indenting the JSON, so it's all crammed together like your group chat 💀
table formatter:
--max-width <integer>— maximum display width,<1to disable; you can also set theCLIFF_MAX_TERM_WIDTHenvironment variable but the parameter takes precedence (it always wins the argument, main character energy)--fit-width— fits the table to your display width, implied if--max-widthis greater than0; set the environment variableCLIFF_FIT_WIDTH=1to always enable it--print-empty— prints an empty table when there's literally no data to show, so at least you get something 😭
🌸 Secret Consumer Create 🌸
$ barbican secret consumer create --service-type-name image \
--resource-type image \
--resource-id 123e4567-e89b-12d3-a456-426614174002 \
0207414d-c23b-47f6-9cef-f44e907ac7a8Okay so consumers are uniquely defined by these three attributes: (service, resource_type, resource_id). Like a trio, bestie, and it's not possible to add a second consumer with the exact same three attributes. The CLI will not throw any error message if you try to create a new consumer with all three same attributes as one that already exists. However — and this is the tea — the new consumer will not actually be created 🫖. So it fails silently, which is giving "ghosted."
💖 Secret Consumer List 💖
$ barbican secret consumer list 0207414d-c23b-47f6-9cef-f44e907ac7a8
+--------------+---------------+--------------------------------------+---------------------+
| Service | Resource type | Resource id | Created |
+--------------+---------------+--------------------------------------+---------------------+
| image | image | 123e4567-e89b-12d3-a456-426614174002 | 2023-01-30T15:54:10 |
+--------------+---------------+--------------------------------------+---------------------+Look at her go, a perfect little table, iconic behavior ✨
🎀 Secret Consumer Delete 🎀
$ barbican secret consumer delete --service-type-name image \
--resource-type image \
--resource-id 123e4567-e89b-12d3-a456-426614174002 \
0207414d-c23b-47f6-9cef-f44e907ac7a8To delete a secret consumer, all three attributes must be provided — no shortcuts, no skipping, all or nothing bestie. Attempting to delete a consumer that doesn't exist will cause the CLI to throw this error message: Not Found: Consumer not found. So rude of it, but at least it tells you 💀
🌈 ACLS 🌈
$ barbican acl <action>A subcommand describing the action to be performed should follow. The subcommands are mostly the same for secret and container ACLs, like sisters fr fr 🫶
Subcommand actions that a user can take for ACLs are:
acl delete— delete ACLs for a secret or container as identified by its href.acl get— retrieve ACLs for a secret or container by providing its href.acl submit— submit ACL on a secret or container as identified by its href.acl user add— add ACL users to a secret or container as identified by its href.acl user remove— remove ACL users from a secret or container as identified by its href.
So the acl get or delete subcommand only takes a secret or container href. All the other ACL commands take additional arguments to specify ACL settings data. Please see the help message for both cases of argument — either secret ref or container ref is required for all of acl actions, no skipping 💅
$ barbican help acl get
usage: barbican acl get [-h] [-f {csv,table,value}] [-c COLUMN]
[--max-width <integer>]
[--quote {all,minimal,none,nonnumeric}]
URI
Retrieve ACLs for a secret or container by providing its href.
positional arguments:
URI The URI reference for the secret or container.
optional arguments:
-h, --help show this help message and exit
output formatters:
output formatter options
-f {csv,table,value}, --format {csv,table,value}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated
table formatter:
--max-width <integer>
Maximum display width, 0 to disable
CSV Formatter:
--quote {all,minimal,none,nonnumeric}
when to include quotes, defaults to nonnumericFollowing is a snippet of related command line options for an ACL modify action, e.g. submit, add or remove:
$ barbican help acl submit/user add/user remove
usage: barbican acl submit [-h] [-f {csv,table,value}] [-c COLUMN]
[--max-width <integer>]
[--quote {all,minimal,none,nonnumeric}]
[--user [USER]]
[--project-access | --no-project-access]
[--operation-type {read}]
URI
....
....
positional arguments:
URI The URI reference for the secret or container.
optional arguments:
-h, --help show this help message and exit
--user [USER], -u [USER]
Keystone userid(s) for ACL.
--project-access Flag to enable project access behavior.
--no-project-access Flag to disable project access behavior.
--operation-type {read}, -o {read}
Type of Barbican operation ACL is set for
....
....Note: The default for the operation-type argument is 'read' because that's literally the only operation currently supported by the Barbican ACL API. So you can totally skip this argument in your CLI call, no need to type it out bestie, save your energy ✨
🦋 ACLs Get 🦋
To get the complete ACL setting for a secret or container, use this ACL action.
$ barbican acl get http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Secret ACL Ref |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| read | False | ['721e27b8505b499e8ab3b38154705b9e', '2d0ee7c681cc4549b6d76769c320d91f'] | 2015-07-21 17:52:01.729370+00:00 | 2015-07-28 02:08:02.455276+00:00 | http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213/acl |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+$ barbican acl get http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Container ACL Ref |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| read | False | ['2d0ee7c681cc4549b6d76769c320d91f'] | 2015-07-28 01:36:55.791381+00:00 | 2015-07-28 02:05:41.175386+00:00 | http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19/acl |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+Secret or container ref is required. If it's missing, it will result in an error, no cap:
$ barbican acl get
usage: barbican acl get [-h] [-f {csv,table,value}] [-c COLUMN]
[--max-width <integer>]
[--quote {all,minimal,none,nonnumeric}]
URI
barbican acl get: error: too few argumentsThe way it just says "too few arguments" like okay calm down 😭
⭐ ACLs Submit ⭐
To submit a complete ACL setting for a secret or container, use this ACL action.
$ barbican acl submit --user 2d0ee7c681cc4549b6d76769c320d91f --user 721e27b8505b499e8ab3b38154705b9e http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213okay bestie so that whole table above? that's the glow-up when the submit goes through with users and project access both living their truth. now let's talk corner cases, because the flags have ✨opinions✨
If the user argument is missing or has no value, then an empty list is passed for users — and plot twist, that's actually the move for removing existing ACL users. If the project access argument isn't provided, then by default project access is enabled (default-on, main character behavior 💅). Wanna turn it off? Just pass no-project-access with no value, periodt.
$ barbican acl submit --user --no-project-access http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213
+----------------+----------------+-------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Secret ACL Ref |
+----------------+----------------+-------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| read | False | [] | 2015-07-21 17:52:01.729370+00:00 | 2015-08-12 09:55:23.043433+00:00 | http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213/acl |
+----------------+----------------+-------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+and yeah, it works on containers too, obviously 🫶
$ barbican acl submit --user 2d0ee7c681cc4549b6d76769c320d91f --no-project-access http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Container ACL Ref |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| read | False | ['2d0ee7c681cc4549b6d76769c320d91f'] | 2015-07-29 22:01:00.878270+00:00 | 2015-08-19 05:56:09.930302+00:00 | http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19/acl |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+🚨 and if you get messy and pass both mutually exclusive flags? bestie no. the CLI simply will not. here's the exact energy you get back:
$ barbican acl submit --project-access --no-project-access http://localhost:9311/v1/secrets/7776adb8-e865-413c-8ccc-4f09c3fe0213
usage: barbican acl submit [-h] [-f {csv,table,value}] [-c COLUMN]
[--max-width <integer>]
[--quote {all,minimal,none,nonnumeric}]
[--user [USER]]
[--project-access | --no-project-access]
[--operation-type {read}]
URI
barbican acl submit: error: argument --no-project-access: not allowed with argument --project-access🎀 ACL Add User(s)
adding more users to a secret or a container? this is the action, iykyk 💖
If the user argument is missing or has no value, then no change is made in ACL users. If the project access argument isn't provided, then no change is made to the existing project access behavior flag. (yeah, this one's the "don't touch what you didn't ask about" sibling of submit. respectful. we stan.)
$ barbican acl user add --user c1d20e4b7e7d4917aee6f0832152269b http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Container ACL Ref |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+
| read | False | ['2d0ee7c681cc4549b6d76769c320d91f', 'c1d20e4b7e7d4917aee6f0832152269b'] | 2015-07-29 22:01:00.878270+00:00 | 2015-08-12 10:08:19.129370+00:00 | http://localhost:9311/v1/containers/83c302c7-86fe-4f07-a277-c4962f121f19/acl |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+------------------------------------------------------------------------------+# Added 2 users for secret (084c2098-66db-4401-8348-d969be0eddaa) earlier via set action.
$ barbican acl user add --user --no-project-access http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Secret ACL Ref |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| read | False | ['721e27b8505b499e8ab3b38154705b9e', '2d0ee7c681cc4549b6d76769c320d91f'] | 2015-08-12 10:09:27.564371+00:00 | 2015-08-12 10:11:09.749980+00:00 | http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa/acl |
+----------------+----------------+--------------------------------------------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+🦋 ACL Remove User(s)
breaking up with an ACL user? valid. this is the action for removing ACL users from a secret or container 🌸
Same ground rules, bestie: if the user argument is missing or has no value, then no change is made in ACL users 🙅♀️ and if the project access argument isn't provided, then no change is made to the existing project access behavior flag.
And the grace note: if a provided userid(s) doesn't exist in the ACL, it's simply ignored — only existing userid(s) get removed. no drama, no error, so iconic of it honestly.
$ barbican acl user remove --user 2d0ee7c681cc4549b6d76769c320d91f --user invalid_user_id http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Secret ACL Ref |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+
| read | False | ['721e27b8505b499e8ab3b38154705b9e'] | 2015-08-12 10:09:27.564371+00:00 | 2015-08-12 10:12:21.842888+00:00 | http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa/acl |
+----------------+----------------+--------------------------------------+----------------------------------+----------------------------------+---------------------------------------------------------------------------+(see how invalid_user_id just… didn't matter? slay. it got skipped like it wasn't even invited 💀)
💜 ACLs Delete
wanna nuke an existing ACL setting for a secret or container? this is the button. 🔥
$ barbican acl delete http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa
$ barbican acl get http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa
+----------------+----------------+-------+---------+---------+---------------------------------------------------------------------------+
| Operation Type | Project Access | Users | Created | Updated | Secret ACL Ref |
+----------------+----------------+-------+---------+---------+---------------------------------------------------------------------------+
| read | True | [] | None | None | http://localhost:9311/v1/secrets/084c2098-66db-4401-8348-d969be0eddaa/acl |
+----------------+----------------+-------+---------+---------+---------------------------------------------------------------------------+look at that fresh-slate energy: Project Access snapped back to True, Users is [], and Created / Updated are both None. born again, no cap ✨
🔐 Authentication
okay so this is the part where we talk about who you are 👑
Keystone Authentication 🫶
The client defers authentication to Keystone Sessions <https://docs.openstack.org/keystoneauth/latest/using-sessions.html>, which provide several authentication plugins in the keystoneauth1.identity namespace. Below we give examples of the most commonly used auth plugins.
Keystone API Version 3 Authentication ⭐
Authentication using Keystone API Version 3 can be achieved using the keystoneauth1.identity.V3Password auth plugin. it's giving "the classic, the icon, the standard" 💅
Example:
from barbicanclient import client
from keystoneauth1 import identity
from keystoneauth1 import sessionauth = identity.V3Password(auth_url='http://localhost:5000/v3', username='admin_user', user_domain_name='Default', password='password', project_name='demo', project_domain_name='Default') sess = session.Session(auth=auth) barbican = client.Client(session=sess)
### 💖 Keystone API Version 2 Authentication 💖
Okay bestie, next flavor: Keystone API Version 2 auth. You can make this happen with the `keystoneauth1.identity.V2Password` auth plugin, and it's honestly <pink>so valid</pink> for older setups.
Example:
from barbicanclient import client from keystoneauth1 import identity from keystoneauth1 import session
auth = identity.V2Password(auth_url='http://localhost:5000/v2.0', username='admin_user', password='password', tenant_name='demo') sess = session.Session(auth=auth) barbican = client.Client(session=sess)
### 🦋 Unauthenticated Context 🦋
Sometimes you lowkey need to work with the client in an unauthenticated context — like when you're using a development instance of Barbican that is not yet configured to use Keystone for authentication. In this case, the Barbican Service endpoint must be provided, in addition to the Project ID that will be used for context (i.e. the project that owns the secrets you'll be working with). <purple>Important little detail, bestie.</purple>
Example:
from barbicanclient import client
barbican = client.Client(endpoint='http://localhost:9311', project_id='123456')
### 🎀 CLI Authentication 🎀
### 🔑 Keystone V3 Authentication 🔑
Barbican can be configured to use Keystone for authentication. The user's credentials can be passed to Barbican via arguments, like this:
$ barbican --os-auth-url <keystone-v3-url> --os-project-domain-id \ <domain id> --os-user-domain-id <user domain id> --os-username <username> \ --os-password <password> --os-project-name <project-name> secret list
This can become annoying and tedious, so authentication via Keystone can also be configured by setting environment variables. Barbican uses the same env variables as `python-keystoneclient` so if you already have keystone client configured you can skip this section. <mint>iykyk</mint> 💅
An example `clientrc` file is provided in the main python-barbicanclient directory.
export OS_PROJECT_NAME=<YourProjectName>
# Either Project Domain ID or Project Domain Name is required export OS_PROJECT_DOMAIN_ID=<YourProjectDomainID> export OS_PROJECT_DOMAIN_NAME=<YourProjectDomainName>
# Either User Domain ID or User Domain Name is required export OS_USER_DOMAIN_ID=<YourUserDomainID> export OS_USER_DOMAIN_NAME=<YourUserDomainName>
# Either User ID or Username can be used export OS_USER_ID =<YourUserID> export OS_USERNAME=<YourUserName>
export OS_PASSWORD=<YourPassword>
# OS_AUTH_URL should be your location of Keystone # Barbican Client defaults to Keystone V3 export OS_AUTH_URL="<YourAuthURL>:5000/v3/" export BARBICAN_ENDPOINT="<YourBarbicanEndpoint>:9311"
Make any appropriate changes to this file. 🫶
You will need to source it into your environment on each load:
source ~/clientrc
If you would like, you can configure your bash to load the variables on each login:
echo "source ~/clientrc" >> ~/.bashrc
### 🪙 Keystone Token Authentication 🪙
Barbican can be configured to use Keystone tokens for authentication. The user's credentials can be passed to Barbican via arguments:
$ barbican --os-auth-url <auth_endpoint> --os-auth-token <auth_token> \ --os-project-id <project_id> secret list
Much like normal password authentication you can specify these values via environmental variables. Refer to Keystone V3 authentication for more information. <yellow>No cap, env vars are the moment.</yellow> ✨
### 🚫 No Auth Mode 🚫
When working with a Barbican instance that does not use Keystone authentication (e.g. during development) you can use the `--no-auth` option. If you do this, you'll have to specify the Barbican endpoint and project ID `--os-project-id`. This is because Barbican normally gets the endpoint and tenant ID from Keystone. <cyan>So don't forget those, bestie.</cyan> 🫡
### 🌈 Client Usage 🌈
To use barbicanclient, you must first create an instance of the `barbicanclient.client.Client <#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. <lavender>That's the whole vibe.</lavender>
See Authentication (`<>`) for more details.
Example:
from barbicanclient import client
barbican = client.Client(...)
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. <pink>Three little icons, one slay client.</pink> 👑
### 🔐 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 ''.join( sys_random.choice(string.ascii_letters + string.digits) for _ in range(length) )
barbican = client.Client(...)
my_secret = barbican.secrets.create() my_secret.name = '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. <mint>Reuse the ref, bestie.</mint> 🎀
Example:
# Retrieve Secret from secret reference
retrieved_secret = barbican.secrets.get(my_secret_ref) my_password = retrieved_secret.payload
### 🍓 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. Here's the mapping of Python types to Barbican Secret Content Types:
- **Python 3 Type `bytes`** → **Barbican Content Type `application/octet-stream`**
- **Python 3 Type `str`** → **Barbican Content Type `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. <red>Do not mess with those manually, fr fr.</red> 💀
### 📦 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.create_key() 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. <blue>Reference girlies stay winning.</blue> 🦋
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). <hotpink>ACTIVE is the green flag here.</hotpink> ✨
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. <purple>Group chat for secrets, basically.</purple> 🫶
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)
### 💅 Secret Consumers 💅
Secret consumers are represented by three attributes: `service`, resource type and resource id. Callers can register secret consumers to indicate that they are using a secret. For instance, in the example below, the caller creates a secret consumer to indicate that the created secret is being used to encrypt a specific Glance image. <rainbow>Main character consumer behavior.</rainbow> 🌈
Secret consumers should be managed using the `barbicanclient.secrets.SecretManager` instance in the `secrets` attribute of the Client and by the corresponding `register_consumer`, `remove_consumer` and `list_consumers` methods.
Example:
# Creating a secret and adding a consumer to it
secret = barbican.secrets.create(name='image encryption key', payload='encryption_key') secret.store()
barbican.secrets.register_consumer( secret.secret_ref, service="image", resource_type="image", resource_id="123e4567-e89b-12d3-a456-426614174002" )
# Listing all the secret's consumers
consumers = barbican.secrets.list_consumers(secret.secret_ref) for consumer in consumers: print(f"Service: {consumer['service']}\t" f"Resource Type: {consumer['resource_type']}\t" f"Resource id: {consumer['resource_id']}")
# Removing the previously created consumer
barbican.secrets.remove_consumer( secret.secret_ref, service="image", resource_type="image", resource_id="123e4567-e89b-12d3-a456-426614174002" )
---
## 🎀 ACLs 🎀
okay so the Access Control List (ACL) feature in Barbican? it's literally the user level access control glow-up for secrets *and* containers. <pink>By default</pink> 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. that's the default vibe. but ACLs let you get ✨specific✨.
bestie, you manage ACLs with the `barbicanclient.acls.ACLManager` instance that lives in the `acls` attribute of the `Client`. that's the spot. 🫶
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.
so the secret or container URI can be used to read **all** of its ACL setting. the returned value is an instance of either `barbicanclient.acls.SecretACL` or `barbicanclient.acls.ContainerACL` — refer to the 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()
ACL settings can also be retrieved <green>directly</green> from the secret or container entity. and here's the cute part: its data is lazy loaded — i.e. the related ACL settings are <hotpink>not</hotpink> read till the `acls` attribute is accessed on the secret or container entity. she waits until you actually need her. main character energy fr fr. 💀
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 you need to <purple>add</purple> users to existing `'read'` ACL settings on a secret or container, the get and submit methods mentioned above are the ones you want, no cap. 🦋
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.
and if you need to <red>remove</red> some users from existing ACL settings on a secret or container? same approach as the add example above — literally just flip it. 🔥
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 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 you need to <yellow>unset</yellow> or delete ACL settings on a secret or container? that's what `barbicanclient.acls.SecretACL.remove()` or `barbicanclient.acls.ContainerACL.remove()` are for. bye bestie 👋✨
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()
---
## 🌈 Key Manager service (barbican) command-line client 🌈
okay so the `barbican` client is the command-line interface (CLI) for the Key Manager service (barbican) API and its extensions. she's the whole package. 👑
this chapter documents **barbican version `4.3.0`**. periodt.
for help on a specific `barbican` command, enter:
$ barbican help COMMAND
### ⭐ barbican usage ⭐
usage: barbican [--version] [-v | -q] [--log-file LOG_FILE] [-h] [--debug] [--no-auth] [--os-identity-api-version <identity-api-version>] [--os-auth-url <auth-url>] [--os-username <auth-user-name>] [--os-user-id <auth-user-id>] [--os-password <auth-password>] [--os-user-domain-id <auth-user-domain-id>] [--os-user-domain-name <auth-user-domain-name>] [--os-tenant-name <auth-tenant-name>] [--os-tenant-id <tenant-id>] [--os-project-id <auth-project-id>] [--os-project-name <auth-project-name>] [--os-project-domain-id <auth-project-domain-id>] [--os-project-domain-name <auth-project-domain-name>] [--os-auth-token <auth-token>] [--endpoint <barbican-url>] [--interface <barbican-interface>] [--service-type <barbican-service-type>] [--service-name <barbican-service-name>] [--region-name <barbican-region-name>] [--barbican-api-version <barbican-api-version>] [--insecure] [--os-cacert <ca-certificate>] [--os-cert <certificate>] [--os-key <key>] [--timeout <seconds>] [--collect-timing]
### 💜 barbican optional arguments 💜
- **`--version`** — show program's version number and exit. that's it, that's the whole flag 💅
- **`-v`, `--verbose`** — Increase verbosity of output. Can be repeated. yes bestie, stack it, keep going 🔥
- **`-q`, `--quiet`** — Suppress output except warnings and errors. silent era. 🤫
- **`--log-file LOG_FILE`** — Specify a file to log output. Disabled by default.
- **`-h`, `--help`** — Show help message and exit.
- **`--debug`** — Show tracebacks on errors. the receipts, basically. 💀
- **`--no-auth`, `-N`** — Do not use authentication. living dangerously, iconic
- **`--os-identity-api-version <identity-api-version>`** — Specify Identity API version to use. Defaults to `env[OS_IDENTITY_API_VERSION]` or `3`.
- **`--os-auth-url <auth-url>`, `-A <auth-url>`** — Defaults to `env[OS_AUTH_URL]`.
- **`--os-username <auth-user-name>`, `-U <auth-user-name>`** — Defaults to `env[OS_USERNAME]`.
- **`--os-user-id <auth-user-id>`** — Defaults to `env[OS_USER_ID]`.
- **`--os-password <auth-password>`, `-P <auth-password>`** — Defaults to `env[OS_PASSWORD]`.
- **`--os-user-domain-id <auth-user-domain-id>`** — Defaults to `env[OS_USER_DOMAIN_ID]`.
- **`--os-user-domain-name <auth-user-domain-name>`** — Defaults to `env[OS_USER_DOMAIN_NAME]`.
- **`--os-tenant-name <auth-tenant-name>`, `-T <auth-tenant-name>`** — Defaults to `env[OS_TENANT_NAME]`.
- **`--os-tenant-id <tenant-id>`, `-I <tenant-id>`** — Defaults to `env[OS_TENANT_ID]`.
- **`--os-project-id <auth-project-id>`** — Another way to specify tenant ID. This option is **mutually exclusive** with `--os-tenant-id`. Defaults to `env[OS_PROJECT_ID]`. pick one bestie, not both 🙈
- **`--os-project-name <auth-project-name>`** — Another way to specify tenant name. This option is **mutually exclusive** with `--os-tenant-name`. Defaults to `env[OS_PROJECT_NAME]`.
- **`--os-project-domain-id <auth-project-domain-id>`** — Defaults to `env[OS_PROJECT_DOMAIN_ID]`.
- **`--os-project-domain-name <auth-project-domain-name>`** — Defaults to `env[OS_PROJECT_DOMAIN_NAME]`.
- **`--os-auth-token <auth-token>`** — Defaults to `env[OS_AUTH_TOKEN]`.
- **`--endpoint <barbican-url>`, `-E <barbican-url>`** — Defaults to `env[BARBICAN_ENDPOINT]`.
- **`--interface <barbican-interface>`** — Defaults to `env[BARBICAN_INTERFACE]`.
- **`--service-type <barbican-service-type>`** — the service type; defaults to `env[BARBICAN_SERVICE_TYPE]` ✨
- **`--service-name <barbican-service-name>`** — the service name; defaults to `env[BARBICAN_SERVICE_NAME]` 💫
- **`--region-name <barbican-region-name>`** — the region name; defaults to `env[BARBICAN_REGION_NAME]` 🌍
- **`--barbican-api-version <barbican-api-version>`** — the Barbican API version; defaults to `env[BARBICAN_API_VERSION]` 🎀
---
### 💅 `barbican acl delete`
usage: barbican acl delete [-h] URI
Bestie, this one nukes the ACLs for a secret *or* a container, identified by its href. Gone. Deleted. Poof 💀
**Positional arguments:**
- `URI` — the URI reference for the secret or container. That's your target, periodt.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit. The classic "wait what does this do again" button 🫶
---
### 🔍 `barbican acl get`
usage: barbican acl get [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] URI
Retrieves the ACLs for a secret or container — just hand it the href and it spills the whole access-control tea ☕✨
**Positional arguments:**
- `URI` — the URI reference for the secret or container.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 📝 `barbican acl submit`
usage: barbican acl submit [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--user [USERS]] [--project-access | --no-project-access] [--operation-type {read}] URI
Submits an ACL onto a secret or container, as identified by its href. This is the "here's who gets access" move 👑
**Positional arguments:**
- `URI` — the URI reference for the secret or container.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--user [USERS]`, `-u [USERS]`** — the Keystone userid(s) for the ACL. Yes bestie, you can pass more than one 💖
- **`--project-access`** — flag to enable project access behavior.
- **`--no-project-access`** — flag to disable project access behavior.
- **`--operation-type {read}`, `-o {read}`** — the type of Barbican operation the ACL is set for. (Just `read` in the menu, iykyk.)
---
### ➕ `barbican acl user add`
usage: barbican acl user add [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--user [USERS]] [--project-access | --no-project-access] [--operation-type {read}] URI
Adds ACL users to a secret or container, identified by its href. Inviting people to the group chat, basically 🫶✨
**Positional arguments:**
- `URI` — the URI reference for the secret or container.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--user [USERS]`, `-u [USERS]`** — the Keystone userid(s) for the ACL.
- **`--project-access`** — flag to enable project access behavior.
- **`--no-project-access`** — flag to disable project access behavior.
- **`--operation-type {read}`, `-o {read}`** — the type of Barbican operation the ACL is set for.
---
### ➖ `barbican acl user remove`
usage: barbican acl user remove [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--user [USERS]] [--project-access | --no-project-access] [--operation-type {read}] URI
Removes ACL users from a secret or container, identified by its href. The reverse of the above — someone's getting quietly removed from the chat 😭💀
**Positional arguments:**
- `URI` — the URI reference for the secret or container.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--user [USERS]`, `-u [USERS]`** — the Keystone userid(s) for the ACL.
- **`--project-access`** — flag to enable project access behavior.
- **`--no-project-access`** — flag to disable project access behavior.
- **`--operation-type {read}`, `-o {read}`** — the type of Barbican operation the ACL is set for.
---
### 🏛️ `barbican ca get`
usage: barbican ca get [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] URI
Retrieves a CA by handing over its URI. Certificate authority reveal time 🌸
**Positional arguments:**
- `URI` — the URI reference for the CA.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 📜 `barbican ca list`
usage: barbican ca list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--limit LIMIT] [--offset OFFSET] [--name NAME]
Lists CAs. All of them. Line 'em up 🎀
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--limit LIMIT`, `-l LIMIT`** — specify the limit to the number of items to list per page (default: 10; maximum: 100).
- **`--offset OFFSET`, `-o OFFSET`** — specify the page offset (default: 0).
- **`--name NAME`, `-n NAME`** — specify the ca name (default: None).
---
### 📦 `barbican secret container create`
usage: barbican secret container create [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] [--name NAME] [--type TYPE] [--secret SECRET]
Stores a container in Barbican. New container, who dis 💅
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--name NAME`, `-n NAME`** — a human-friendly name. Give it a cute one.
- **`--type TYPE`** — type of container to create (default: `generic`).
- **`--secret SECRET`, `-s SECRET`** — one secret to store in a container (can be set multiple times). Example:
--secret "private_key=https://url.test/v1/secrets/1-2-3-4"
---
### 🗑️ `barbican secret container delete`
usage: barbican secret container delete [-h] URI
Deletes a container by providing its href. Bye bye container 👋💀
**Positional arguments:**
- `URI` — the URI reference for the container
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 🔎 `barbican secret container get`
usage: barbican secret container get [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] URI
Retrieves a container by providing its URI. Show me what's inside ✨
**Positional arguments:**
- `URI` — the URI reference for the container.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 📋 `barbican secret container list`
usage: barbican secret container list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--limit LIMIT] [--offset OFFSET] [--name NAME] [--type TYPE]
Lists containers. Scroll the container feed, bestie 🦋
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--limit LIMIT`, `-l LIMIT`** — specify the limit to the number of items to list per page (default: 10; maximum: 100).
- **`--offset OFFSET`, `-o OFFSET`** — specify the page offset (default: 0).
- **`--name NAME`, `-n NAME`** — specify the container name (default: None).
- **`--type TYPE`, `-t TYPE`** — specify the type filter for the list (default: None).
---
### 💀 `barbican secret delete`
usage: barbican secret delete [-h] [--force] URI
Deletes a secret by providing its URI. This is the point of no return, ngl 😭
**Positional arguments:**
- `URI` — the URI reference for the secret
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--force`, `-f`** — if specified, forces the deletion of secrets that have consumers.
> ⚠️ Heads up: `--force` is literally for deleting secrets that still have consumers. That's a real "are you sure bestie" moment — read that flag twice before you send it 🔥
---
### 🔓 `barbican secret get`
usage: barbican secret get [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] [--decrypt] [--payload] [--payload_content_type PAYLOAD_CONTENT_TYPE] URI
Retrieves a secret by providing its URI 🎀
**Positional arguments:**
- `URI` — the URI reference for the secret.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--decrypt`, `-d`** — if specified, retrieve the unencrypted secret data; the data type can be specified with `--payload_content_type`.
- **`--payload`, `-p`** — if specified, retrieve the unencrypted secret data; the data type can be specified with `--payload_content_type`. If the user wishes to only retrieve the value of the payload they must add `"-f value"` to format returning only the value of the payload.
- **`--payload_content_type PAYLOAD_CONTENT_TYPE`, `-t PAYLOAD_CONTENT_TYPE`** — the content type of the decrypted secret (default: `text/plain`).
---
### 🗂️ `barbican secret list`
usage: barbican secret list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--limit LIMIT] [--offset OFFSET] [--name NAME] [--algorithm ALGORITHM] [--bit-length BIT_LENGTH] [--mode MODE]
Lists secrets. Filter her however you like 🔥
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--limit LIMIT`, `-l LIMIT`** — specify the limit to the number of items to list per page (default: 10; maximum: 100).
- **`--offset OFFSET`, `-o OFFSET`** — specify the page offset (default: 0).
- **`--name NAME`, `-n NAME`** — specify the secret name (default: None).
- **`--algorithm` *ALGORITHM*, `-a` *ALGORITHM*** — the algorithm filter for the list (default: `None`). yes, the default is literally `None`, she's not picky 💅
- **`--bit-length` *BIT_LENGTH*, `-b` *BIT_LENGTH*** — the bit length filter for the list (default: `0`).
- **`--mode` *MODE*, `-m` *MODE*** — the algorithm mode filter for the list (default: `None`).
---
### 🎀 barbican secret order create 🎀
barbican secret order create [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] [--name NAME] [--algorithm ALGORITHM] [--bit-length BIT_LENGTH] [--mode MODE] [--payload-content-type PAYLOAD_CONTENT_TYPE] [--expiration EXPIRATION] [--request-type REQUEST_TYPE] [--subject-dn SUBJECT_DN] [--source-container-ref SOURCE_CONTAINER_REF] [--ca-id CA_ID] [--profile PROFILE] [--request-file REQUEST_FILE] type
Create a new order. fresh order, hot off the press 🔥
**Positional arguments:**
- `type` — the type of the order (`key`, `asymmetric`, `certificate`) to create.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--name` *NAME*, `-n` *NAME*** — a human-friendly name.
- **`--algorithm` *ALGORITHM*, `-a` *ALGORITHM*** — the algorithm to be used with the requested key (default: `aes`).
- **`--bit-length` *BIT_LENGTH*, `-b` *BIT_LENGTH*** — the bit length of the requested secret key (default: `256`).
- **`--mode` *MODE*, `-m` *MODE*** — the algorithm mode to be used with the requested key (default: `cbc`).
- **`--payload-content-type` *PAYLOAD_CONTENT_TYPE*, `-t` *PAYLOAD_CONTENT_TYPE*** — the type/format of the secret to be generated (default: `application/octet-stream`).
- **`--expiration` *EXPIRATION*, `-x` *EXPIRATION*** — the expiration time for the secret in ISO 8601 format.
- **`--request-type` *REQUEST_TYPE*** — the type of the certificate request.
- **`--subject-dn` *SUBJECT_DN*** — the subject of the certificate.
- **`--source-container-ref` *SOURCE_CONTAINER_REF*** — the source of the certificate when using stored-key requests.
- **`--ca-id` *CA_ID*** — the identifier of the CA to use for the certificate request.
- **`--profile` *PROFILE*** — the profile of certificate to use.
- **`--request-file` *REQUEST_FILE*** — the file containing the CSR.
---
### 💜 barbican secret order delete 💜
barbican secret order delete [-h] URI
Delete an order by providing its href. bye bestie 👋
**Positional arguments:**
- `URI` — The URI reference for the order
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 🌈 barbican secret order get 🌈
barbican secret order get [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] URI
Retrieve an order by providing its URI.
**Positional arguments:**
- `URI` — The URI reference order.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 🦋 barbican secret order list 🦋
barbican secret order list [-h] [-f {csv,html,json,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--quote {all,minimal,none,nonnumeric}] [--limit LIMIT] [--offset OFFSET]
List orders. the whole roster, lined up ✨
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--limit` *LIMIT*, `-l` *LIMIT*** — specify the limit to the number of items to list per page (default: `10`; maximum: `100`)
- **`--offset` *OFFSET*, `-o` *OFFSET*** — specify the page offset (default: `0`)
---
### 🍓 barbican secret store 🍓
barbican secret store [-h] [-f {html,json,shell,table,value,yaml}] [-c COLUMN] [--max-width <integer>] [--print-empty] [--noindent] [--prefix PREFIX] [--name NAME] [--payload PAYLOAD] [--secret-type SECRET_TYPE] [--payload-content-type PAYLOAD_CONTENT_TYPE] [--payload-content-encoding PAYLOAD_CONTENT_ENCODING] [--algorithm ALGORITHM] [--bit-length BIT_LENGTH] [--mode MODE] [--expiration EXPIRATION]
Store a secret in Barbican. put it in the vault, it's safe with us 🔐
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--name` *NAME*, `-n` *NAME*** — a human-friendly name.
- **`--payload` *PAYLOAD*, `-p` *PAYLOAD*** — the unencrypted secret; if provided, you must also provide a `payload_content_type`
- **`--secret-type` *SECRET_TYPE*, `-s` *SECRET_TYPE*** — the secret type; must be one of `symmetric`, `public`, `private`, `certificate`, `passphrase`, `opaque` (default)
- **`--payload-content-type` *PAYLOAD_CONTENT_TYPE*, `-t` *PAYLOAD_CONTENT_TYPE*** — the type/format of the provided secret data; `"text/plain"` is assumed to be UTF-8; **required when `--payload` is supplied.**
- **`--payload-content-encoding` *PAYLOAD_CONTENT_ENCODING*, `-e` *PAYLOAD_CONTENT_ENCODING*** — **required if `--payload-content-type` is `"application/octet-stream"`.**
- **`--algorithm` *ALGORITHM*, `-a` *ALGORITHM*** — the algorithm (default: `aes`).
- **`--bit-length` *BIT_LENGTH*, `-b` *BIT_LENGTH*** — the bit length (default: `256`).
- **`--mode` *MODE*, `-m` *MODE*** — the algorithm mode; used only for reference (default: `cbc`)
- **`--expiration` *EXPIRATION*, `-x` *EXPIRATION*** — the expiration time for the secret in ISO 8601 format.
---
### 🧚 barbican secret update 🧚
barbican secret update [-h] URI payload
Update a secret with no payload in Barbican.
**Positional arguments:**
- `URI` — The URI reference for the secret.
- `payload` — the unencrypted secret
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
---
### 👑 barbican secret consumer create 👑
barbican secret consumer create [-h] --service-type-name SERVICE_TYPE_NAME --resource-type RESOURCE_TYPE --resource-id RESOURCE_ID URI
Create a consumer for a secret.
**Positional arguments:**
- `URI` — The URI reference for the secret.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--service-type-name` *SERVICE_TYPE_NAME*, `-s` *SERVICE_TYPE_NAME*** — the service that will consume the secret
- **`--resource-type` *RESOURCE_TYPE*, `-t` *RESOURCE_TYPE*** — the type of resource that will consume the secret
- **`--resource-id` *RESOURCE_ID*, `-i` *RESOURCE_ID*** — the id of the resource that will consume the secret
---
### 💀 barbican secret consumer delete 💀
barbican secret consumer delete [-h] --service-type-name SERVICE_TYPE_NAME --resource-type RESOURCE_TYPE --resource-id RESOURCE_ID URI
Delete a consumer from a secret. no more access, blocked 💅
**Positional arguments:**
- `URI` — The URI reference for the secret.
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--service-type-name` *SERVICE_TYPE_NAME*, `-s` *SERVICE_TYPE_NAME*** — the service that will consume the secret
- **`--resource-type` *RESOURCE_TYPE*, `-t` *RESOURCE_TYPE*** — the type of resource that will consume the secret
- **`--resource-id` *RESOURCE_ID*, `-i` *RESOURCE_ID*** — the id of the resource that will consume the secret
---
### 🌸 barbican secret consumer list 🌸
barbican secret consumer list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN] [--quote {all,minimal,none,nonnumeric}] [--noindent] [--max-width <integer>] [--fit-width] [--print-empty] [--sort-column SORT_COLUMN] [--sort-ascending | --sort-descending] [--limit LIMIT] [--offset OFFSET] URI
List consumers of a secret. who's got the keys? 👀
**Positional arguments:**
- `URI` — The URI reference for the secret
**Optional arguments:**
- **`-h`, `--help`** — show this help message and exit.
- **`--limit` *LIMIT*, `-l` *LIMIT*** — specify the limit to the number of items to list per page (default: `10`; maximum: `100`)
- **`--offset` *OFFSET*, `-o` *OFFSET*** — specify the page offset (default: `0`)
**Output formatters:**
- **`-f {csv,json,table,value,yaml}`, `--format {csv,json,table,value,yaml}`** — the output format, defaults to `table`
- **`-c` *COLUMN*, `--column` *COLUMN*** — specify the column(s) to include, can be repeated to show multiple columns
- **`--sort-column` *SORT_COLUMN*** — specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
- **`--sort-ascending`** — sort the column(s) in ascending order
- **`--sort-descending`** — sort the column(s) in descending order
**CSV Formatter:**
- **`--quote {all,minimal,none,nonnumeric}`** — when to include quotes, defaults to `nonnumeric`
**json formatter:**
- **`--noindent`** — whether to disable indenting the JSON
**table formatter:**
- **`--max-width <integer>`** — Maximum display width, `<1` to disable. You can also use the `CLIFF_MAX_TERM_WIDTH` environment variable, but the parameter takes precedence.
- **`--fit-width`** — Fit the table to the display width. Implied if `--max-width` greater than `0`. Set the environment variable `CLIFF_FIT_WIDTH=1` to always enable
- **`--print-empty`** — Print empty table if there is no data to show.
# 🛠️ CONTRIBUTOR DOCUMENTATION 🛠️
## Contributing 💖
okay so if you wanna help build OpenStack you literally have to follow the steps on this page first, no skipping bestie:
https://docs.openstack.org/infra/manual/developers.html
once you've done all that, your changes to OpenStack go in for review via the Gerrit tool, following the workflow documented right here:
https://docs.openstack.org/infra/manual/developers.html# development-workflow
> 🚨 Pull requests submitted through GitHub will be ignored. like, for real, they will not even look at it. don't do it to yourself 😭
bugs go on Launchpad, **not** GitHub:
https://bugs.launchpad.net/python-barbicanclient
---
## Writing and Running Barbican Client Tests 🧪
so every single code review submitted to the `python-barbicanclient` project runs a bunch of gating jobs — these are the icons keeping regression issues out of `python-barbicanclient`. which means, yeah, a `python-barbicanclient` developer should lowkey be familiar with running `python-barbicanclient` tests locally. it's giving "know your tools" energy.
for your convenience we provide the ability to run **all** tests through the `tox` utility. if tox is new to you, please refer to the tox documentation for assistance:
https://tox.readthedocs.org/en/latest/
---
## Unit Tests 🌸
we follow the Tested Runtimes as defined by the Technical Committe every cycle 💅
https://governance.openstack.org/tc/reference/project-testing-interface.html#tested-runtimes
all available test environments within the tox configuration will execute when you call `tox`. but if you want to run them independently, you can absolutely do that:
Executes tests on Python 3.9
tox -e py39
> ⭐ **Note:** if you do not have the appropriate Python versions available, consider setting up PyEnv to install multiple versions of Python. see the documentation "setting up a Barbican development environment":
>
> ```
> https://github.com/openstack/barbican/blob/master/doc/source/
> contributor/dev.rst
> ```
> ⭐ **Note:** individual unit tests can also be run, using the following commands:
>
> ```
> # runs a single test with the function named
> # test_should_entity_str
> tox -e py39 -- test_should_entity_str
>
> # runs only tests in the WhenTestingSecrets class and
> # the WhenTestingOrderManager class
> tox -e p39 -- '(WhenTestingSecrets|WhenTestingOrderManager)'
> ```
>
> the function name or class specified **must** be one located in the `barbicanclient/tests` directory.
>
> groups of tests can also be run with a regex match after the `--`. for more info on what can be done with stestr, please see:
>
> ```
> https://stestr.readthedocs.io/en/latest/
> ```
you can also setup breakpoints in the unit tests 🐛 — iconic debugging behavior honestly. this is done by adding `import pdb; pdb.set_trace()` to the line of the unit test you want to examine, then running:
tox -e debug
> ⭐ **Note:** for a list of `pdb` commands, please see:
>
> ```
> https://docs.python.org/2/
> library/pdb.html
> ```
---
## Functional Tests 🔥
unlike running unit tests, the functional tests **require** Barbican and Keystone services to be running in order to execute. no services, no tests, periodt. for more info on setting up a Barbican development environment and using Keystone with Barbican, see our accompanying project documentation:
https://github.com/openstack/barbican/blob/master/doc/source/contributor/dev .rst
https://github.com/openstack/ barbican/blob/master/doc/source/configuration/keystone.rst
a configuration file for functional tests must be edited before the tests can be run. in the top-level directory of the `python-barbicanclient`, edit `/etc/functional_tests.conf` to the values you setup in Keystone 🎀
[DEFAULT]
Leaving this as a placeholder
[keymanager]
Replace values that represent barbican server and user information
url=http://localhost:9311 username=barbican password=secretservice project_name=service project_id=service #max_payload_size=10000 project_domain_name=Default
[identity]
Replace these with values that represent your identity configuration
uri=http://localhost:5000/v2.0 uri_v3=http://localhost:5000/v3 auth_version=v3
username=admin tenant_name=admin password=password domain_name=Default
admin_username=admin admin_tenant_name=admin admin_password=password admin_domain_name=Default
[identity-feature-enabled]
Leaving this as a placeholder
once you have the appropriate services running and configured you can execute the functional tests through tox:
Execute Barbican Functional Tests
tox -e functional
> ⭐ **Note:** in order to run individual functional test functions, you must use the following commands:
>
> ```
> # runs only tests in the test_secrets.py file
> tox -e functional -- client/v1/functional/test_secrets.py
>
> # runs only tests in the SecretsTestCase class
> tox -e functional -- client/v1/functional/test_secrets.py:\
> SecretsTestCase
>
> # runs a single test with the function named
> # test_secret_create_defaults_check_content_types
> tox -e functional -- client/v1/functional/test_secrets.py:\
> SecretsTestCase.test_secret_create_defaults_check_content_types
> ```
>
> the path specified must be one located in the `functionaltests` directory.
---
## Remote Debugging 🕵️♀️
so you wanna be able to hit break-points on API calls? you gotta use remote debugging, bestie. this is done by adding `import rpdb; rpdb.set_trace()` to the line of the API call you wish to test. for example, adding the breakpoint in `def create` in `barbicanclient.secrets.py` will allow you to hit the breakpoint whenever the `create` function is called ✨
> ⭐ **Note:** after performing the POST the application will freeze. in order to use `rpdb`, you must open up another terminal and run the following:
>
> ```
> # enter rpdb using telnet
> telnet localhost 4444
> ```
>
> once in `rpdb`, you can use the same commands as `pdb`, as seen here:
>
> ```
> https://docs.python.org/2/library/pdb.html
> ```
---
# 📚 REFERENCE 📚
## Client 👑
`barbicanclient.client.Client(version=None, session=None, *args, **kwargs)`
Barbican client used to interact with barbican service. your main character for talking to Barbican 💅
**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 🌈
### `add_secret_metadata(secret_ref, key, value)`
Add or update a single metadata key-value pair ✨
### `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. so like, they exist but they're not *out there* yet, yk?
**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**
still under `delete()`'s **Raises** list, bestie:
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `delete_secret_metadata(secret_ref, key)` — bye-bye, one metadata key 🎀
Delete a specific metadata key. It’s giving surgical, lowkey.
**Parameters**
- **`secret_ref`** (*str*) — Full HATEOAS reference to a Secret, or a UUID
- **`key`** (*str*) — Metadata key to delete
**Raises**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `get(secret_ref, payload_content_type=None)` — pull up a Secret from Barbican ✨
Retrieve an existing Secret from Barbican. Main character retrieval energy, fr.
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `get_secret_metadata(secret_ref, key=None)` — metadata reveal 🌸
Get secret metadata. It’s the little info era.
**Parameters**
- **`secret_ref`** (*str*) — Full HATEOAS reference to a Secret, or a UUID
- **`key`** (*str*) — Optional specific metadata key to retrieve
**Returns**
Dictionary containing metadata
**Raises**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `list(limit=10, offset=0, name=None, algorithm=None, mode=None, bits=0, secret_type=None, created=None, updated=None, expiration=None, sort=None)` — the Secret lineup 👑
List Secrets for the project. This is the group-chat roster of your secrets, no cap.
list(limit=10, offset=0, name=None, algorithm=None, mode=None, bits=0, secret_type=None, created=None, updated=None, expiration=None, sort=None)
This method uses the `limit` and `offset` parameters for paging, and also supports filtering. Paging + filtering = organized bestie behavior 💅
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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `list_consumers(secret_ref, limit=10, offset=0)` — who’s consuming this secret? 🫶
List consumers of the secret. It’s giving “who’s in my business” but, like, officially.
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
---
### `register_consumer(secret_ref, service, resource_type, resource_id)` — add a consumer to the secret 🦋
Add a consumer to the secret. Officially linking them to the secret, iykyk.
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
- **`NotImplementedError`** — When using microversion `1.0`
---
### `remove_consumer(secret_ref, service, resource_type, resource_id)` — unlink that consumer 💔
Remove a consumer from the secret. Respectfully detaching the vibes.
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🔐
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 🙈
**Raises** (continued)
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
### `set_secret_metadata(secret_ref, metadata)` 🌸
Set secret metadata — and bestie, it **replaces all existing metadata**. The whole little metadata scrapbook gets swapped out, periodt. 💅
### `update(secret_ref, payload=None)` 🔥
Update an existing Secret in Barbican. Literally that’s the gig. ✨
**Parameters**
- `secret_ref` (`str`) — Full HATEOAS reference to a Secret, or a UUID 🫶
- `payload` (`str`) — New payload to add to secret
**Raises**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
### 🌟 `barbicanclient.v1.secrets.Secret` 🌟
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. Very main character energy for your sensitive stuff, ngl.
Secret objects should **not** be instantiated directly. 🚫
You should use the `create` or `get` methods of the `barbicanclient.secrets.SecretManager` instead. That’s the move, iykyk.
**`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 🛒
### `barbicanclient.v1.orders.OrderManager` 🧾
class barbicanclient.v1.orders.OrderManager(api)
Entity Manager for Order entitites — yes bestie, that’s the spelling in the source 😭.
**`create_asymmetric(name=None, algorithm=None, bit_length=None, pass_phrase=None, payload_content_type=None, expiration=None)`** 🦋
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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
**`create_key(name=None, algorithm=None, bit_length=None, mode=None, payload_content_type=None, expiration=None)`** 🔑
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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
**`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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
**`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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses 💀
### `barbicanclient.v1.orders.Order` 🧾
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. 🚀
### `barbicanclient.v1.orders.KeyOrder` 🔑
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. 💅
### `barbicanclient.v1.orders.AsymmetricOrder` 🦋
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 🎁
### `barbicanclient.v1.containers.ContainerManager` 📦
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. No cap.
**`create(name=None, secrets=None)`** ✨
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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses 🙈
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses 😭
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
### `create_certificate(name=None, certificate=None, intermediates=None, private_key=None, private_key_passphrase=None)`
Factory method for `CertificateContainer` objects ✨
The `CertificateContainer` objects you get back from this method have **not yet been stored in Barbican** — not stored, not saved, not committed, periodt 🫶
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `create_rsa(name=None, public_key=None, private_key=None, private_key_passphrase=None)`
Factory method for `RSAContainer` objects 🔐
The `RSAContainer` objects from this one also have **not yet been stored in Barbican** — same energy, different container 💅
**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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `delete(container_ref)`
Delete a Container from Barbican 🗑️
**Parameters**
- `container_ref` — Full HATEOAS reference to a Container, or a UUID
**Raises**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `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)`
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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `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**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
---
### `class barbicanclient.v1.containers.Container`
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`
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`
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 or UUID
**Returns** — CA object retrieved from Barbican
**Return type** — `barbicanclient.v1.cas.CA`
**Raises**
- **`barbicanclient.exceptions.HTTPAuthError`** — 401 Responses
- **`barbicanclient.exceptions.HTTPClientError`** — 4xx Responses
- **`barbicanclient.exceptions.HTTPServerError`** — 5xx Responses
**`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. 💖
**Returns** — `list` 💫
**Raises** 😭
- `barbicanclient.exceptions.HTTPAuthError` — 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — 4xx Responses
- `barbicanclient.exceptions.HTTPServerError` — 5xx Responses
---
### 🏛️ class `barbicanclient.v1.cas.CA` ✨
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. Like, the whole CA vibe, no cap.
**Certificate authority** 🎀
> CA objects should **not** be instantiated directly, bestie. Not even once. You should use the `create` or `get` methods of the `barbicanclient.cas.CAManager` instead. That's the whole assignment, okay? 👑
---
## 🦋 ACLs 🦋
### class `barbicanclient.v1.acls.ACLManager` 🌸
class barbicanclient.v1.acls.ACLManager(api)
Entity Manager for Secret or Container ACL entities. It's giving access-control main character energy 🔥
#### `create` 🫶
create(entity_ref=None, users=None, project_access=None, operation_type='read', ref_type=None)
Factory method for creating ACL entity. Iconic. ✨
ACL object returned by this method have **not yet** been stored in Barbican. So like, it exists locally and that's it — it's not on the server yet, iykyk.
Input `entity_ref` is used to determine whether ACL object type needs to be `barbicanclient.acls.SecretACL` or `barbicanclient.acls.ContainerACL`. Detective work but make it cute 🕵️♀️
**Parameters**
- **`entity_ref`** (*str*) — Full HATEOAS reference to a secret or container, or a UUID.
- **`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
- **`ref_type`** (*str*) — Type of the resource referenced by `entity_ref`. This is required when UUID is used for `entity_ref`
**Returns** — ACL object instance
**Return type** — `barbicanclient.v1.acls.SecretACL` or `barbicanclient.v1.acls.ContainerACL`
#### `get` 💜
get(entity_ref, ref_type=None)
Retrieve existing ACLs for a secret or container found in Barbican. Going and fetching the real thing, periodt 🎀
**Parameters**
- **`entity_ref`** (*str*) — Full HATEOAS reference to a secret or container, or a UUID.
- **`ref_type`** (*str*) — Type of the resource referenced by `entity_ref`. This is required when UUID is used for `entity_ref`
**Returns** — ACL entity object instance
**Return type** — `barbicanclient.v1.acls.SecretACL` or `barbicanclient.v1.acls.ContainerACL`
**Raises** 😭
- `barbicanclient.exceptions.HTTPAuthError` — 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — 4xx Responses
---
### class `barbicanclient.v1.acls.SecretACL` 🔐
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. That's literally the whole point of it, bestie 💅
**Parameters**
- **`api`** — client instance reference
- **`entity_ref`** (*str*) — Full HATEOAS reference to a secret or container, or a UUID.
- **`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` ⭐
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. Out with the old, in with the new 💅
This just adds to local entity and have not yet applied these changes to server. So don't @ me when it's not saved yet, mkay? 🙈
**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. Simple as that, bestie.
#### property `entity_uuid` 🦋
Entity UUID
#### `get(operation_type)` 🔎
get(operation_type)
Get operation specific ACL instance.
**Parameters**
- **`operation_type`** (*str*) — Type indicating which operation's ACL setting is needed.
#### `load_acls_data()` ✨
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. Fresh start energy, we love to see it 🌈
**Raises** 😭
- `barbicanclient.exceptions.HTTPAuthError` — 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — 4xx Responses
- `barbicanclient.exceptions.HTTPServerError` — 5xx Responses
#### property `operation_acls` 💖
List of operation specific ACL settings.
#### `remove()` 💀
remove()
Remove Barbican ACLs setting defined for a secret or container. Yeeting the ACLs, respectfully 🫶
**Raises** 😭
- `barbicanclient.exceptions.HTTPAuthError` — 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — 4xx Responses
#### `submit()` 👑
submit()
Submits ACLs for a secret or a container defined in server. Sending it. Making it official ✨
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. Read that twice, bestie, because the None-means-remove bit is sneaky 🙈
**Returns** — `str` `acl_ref`: Full HATEOAS reference to a secret or container ACL.
**Raises** 😭
- `barbicanclient.exceptions.HTTPAuthError` — 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — 4xx Responses
- `barbicanclient.exceptions.HTTPServerError` — 5xx Responses
---
### class `barbicanclient.v1.acls.ContainerACL` 🎁
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, or a UUID.
- **`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*) — a time string that says when the ACL was created. Ngl this one only shows up when we're populating data from the api response — you don't need to pass it in as client input. 💅
- **`updated`** (*str*) — same deal, a time string for the ACL's last update timestamp. Also only populated from the api response, also not needed in client input. Two little ghost fields, iconic behaviour honestly 🫶
---
### ✨ `add_operation_acl(users=None, project_access=None, operation_type=None, created=None, updated=None)`
Okay so this one adds ACL settings to the entity for one specific operation type. Bestie listen: if an ACL for that matching `operation_type` already exists, it **replaces** it with a shiny new `PerOperationACL` object built from the inputs you gave it. If there isn't one yet, it just appends a brand new `PerOperationACL` object onto the existing per operation ACL list. Slay. 💅
> Heads up though: this only adds to the **local** entity, okay? It has **not** applied these changes to the server yet. Local vibes only, no cap. ✨
**Parameters**
- **`users`** (*List* or *None*) — list of Keystone userid(s) to be used in the ACL.
- **`project_access`** (*bool*) — flag indicating project access behaviour.
- **`operation_type`** (*str*) — the type telling us which class of Barbican operations this ACL is defined for, e.g. `'read'` operations.
- **`created`** (*str*) — time string indicating ACL create timestamp. Only populated when pulling data from the api response. Not needed in client input, so don't stress 🍓
- **`updated`** (*str*) — time string indicating ACL last update timestamp. Also only populated from the api response, also not needed in client input.
---
### ✨ property `entity_ref`
The Entity URI reference. That's it, that's the whole vibe. 🔥
---
### ✨ property `entity_uuid`
The Entity UUID. Short and sweet, main character energy 👑
---
### ✨ `get(operation_type)`
Gets you the operation-specific ACL instance — like, the ACL that belongs to *that one* operation. 🎀
**Parameters**
- `operation_type` (*str*) — the type indicating which operation's ACL setting you actually want.
---
### ✨ `load_acls_data()`
Loads the ACL entity from the Barbican server using its `acl_ref`. ✨
Here's the tea: it **clears** the existing list of per operation ACL settings if there is one, then populates the current ACL entity with the ACL settings it received from the Barbican server. Fresh start, new data, we love to see it 💖
**Raises**
- `barbicanclient.exceptions.HTTPAuthError` — for 401 Responses 😭
- `barbicanclient.exceptions.HTTPClientError` — for 4xx Responses
- `barbicanclient.exceptions.HTTPServerError` — for 5xx Responses 💀
---
### ✨ property `operation_acls`
The list of operation-specific ACL settings. A whole little list of them 🦋
---
### ✨ `remove()`
Removes the Barbican ACLs setting defined for a secret or container. Bye bye ACLs, it's giving spring cleaning 🌸
**Raises**
- `barbicanclient.exceptions.HTTPAuthError` — for 401 Responses
- `barbicanclient.exceptions.HTTPClientError` — for 4xx Responses
---
### ✨ `submit()`
Submits the ACLs for a secret or a container that's defined in the server. Let's go, time to actually push it 🚀
So in the existing-ACL case, this **overwrites** the existing ACL setting with the inputs you provided. And if your input `users` are `None` or an empty list, this will **remove** the existing ACL users if there are any. Meanwhile, if the input `project_access` flag is `None`, then the default project access behaviour gets enabled. Defaults doing their little default dance 💅
**Returns**
`str acl_ref`: the full HATEOAS reference to a secret or container ACL. Full. HATEOAS. Reference. Obsessed ✨
**Raises**
- `barbicanclient.exceptions.HTTPAuthError` — for 401 Responses 😭
- `barbicanclient.exceptions.HTTPClientError` — for 4xx Responses
- `barbicanclient.exceptions.HTTPServerError` — for 5xx Responses 💀
---
## 🎀 Exceptions 🎀
The whole error family, assembled. Every one of them, no skips 👑
`exception` `barbicanclient.exceptions.BarbicanException`
`exception` `barbicanclient.exceptions.HTTPAuthError(message, status_code=401)` — raised for 401 Unauthorized responses from the server. Bestie got told no 🙈
`exception` `barbicanclient.exceptions.HTTPClientError(message, status_code=0)` — raised for 4xx responses from the server.
`exception` `barbicanclient.exceptions.HTTPError(message, status_code=0)` — the base exception for HTTP errors. The og parent, the main character 🌟
`exception` `barbicanclient.exceptions.HTTPServerError(message, status_code=0)` — raised for 5xx responses from the server. 💀
`exception` `barbicanclient.exceptions.PayloadException`
`exception` `barbicanclient.exceptions.SecretHasConsumers` — the secret has consumers. That's literally the whole note. The secret is *taken*, apparently 😭
`exception` `barbicanclient.exceptions.UnsupportedVersion` — you're trying to use an unsupported version of the API. Respectfully, update your vibe 🌈
---
## 🌸 Indices and tables 🌸
- Index
- Module Index
- Search Page
All the little navigation corners of the docs, keeping you oriented 🧚
---
## 💜 Author 💜
Author name not set. Truly the mystery icon of our generation 🕵️♀️
## 💜 Copyright 💜
`2014, OpenStack Foundation`
---
aaaand that's the whole page bestie, we made it to the end 🫶✨ Version `7.6.0`, dated `Jan 02, 1980` (yes, the date is a whole vibe of its own, don't ask questions 💀), filed under `PYTHON-BARBICANCLIENT(1)`. Go forth and ACL responsibly, mwah 💅🎀
📦 where this page comes from
- nixpkgs unstable: python3.13-python-barbicanclient 7.6.0
- nixpkgs unstable: python3.14-python-barbicanclient 7.6.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms