Command Line Client

keep

keep is a command line interface to the Barbican API.

Keystone Authentication

keep can be configured to use keystone for authentication. This can be done by passing your keystone credentials as arguments to keep.

$ keep --os-auth-url <keystone-url> --os-username <username> --os-password <password> --os-tenant-name <tenant>

Passing the credentials on every command will quickly become tedious, so keep authentication using keystone can also be configured by setting environment variables. keep uses the same env variables as python-keystoneclient so if you already have keystone client configured, you can skip past this section.

An example clientrc file is provided in the main python-barbicanclient directory.

export OS_AUTH_URL="http://keystone-int.cloudkeep.io:5000/v2.0/"
export OS_USERNAME=demo
export OS_PASSWORD=password
export OS_TENANT_NAME=demo
export OS_TENANT_ID=your-keystone-id
export BARBICAN_ENDPOINT="http://api-01-int.cloudkeep.io:9311/v1/"

Make any appropriate changes to this file, and then copy it to your home directory.

Now, source it into your environment.

source ~/clientrc

Finally, configure bash to load the variables on each login.

echo "source ~/clientrc" >> ~/.bashrc

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 --endpoint and tenant ID --os-tenant-id. This is because keep normally gets the endpoint and tenant ID from keystone.

Usage

usage: keep [-h] [--no-auth | --os-auth-url <auth-url>]
            [--os-username <auth-user-name>] [--os-password <auth-password>]
            [--os-tenant-name <auth-tenant-name>] [--os-tenant-id <tenant-id>]
            [--endpoint <barbican-url>]
            <entity> <action> ...

The examples below assume that credentials have been saved to your environment. If you don't have variables saved to your environment or you wish to use different credentials than those defined, any of the optional arguments listed above may be passed to keep.

keep takes a positional argument <entity>, which specifies whether you wish to operate on a secret or an order.

$ keep secret <action>

$ keep order <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. For simplicity, secrets will be operated on in the following examples.

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.

$  keep secret get -h
usage: keep <entity> get [-h] [--decrypt]
                         [--payload_content_type PAYLOAD_CONTENT_TYPE]
                         URI

positional arguments:
  URI                   The URI reference for the secret or order.

optional arguments:
  -h, --help            show this help message and exit
  --decrypt, -d         if specified, keep will retrieve the unencrypted
                        secret data; the data type can be specified with
                        --payload-content-type (only used for secrets).
  --payload_content_type PAYLOAD_CONTENT_TYPE, -t PAYLOAD_CONTENT_TYPE
                        the content type of the decrypted secret (default:
                        text/plain; only used for secrets)

create

$ keep secret store -n mysecret -p 'top secret data' -t 'text/plain'
http://api-01-int.cloudkeep.io:9311/v1/test_tenant/secrets/cc9d7a05-4d48-454b-8578-51decb84a8d9

get

Let's get the secret we just created using its URI.

$ keep secret get http://api-01-int.cloudkeep.io:9311/v1/test_tenant/secrets/cc9d7a05-4d48-454b-8578-51decb84a8d9
Secret - href: http://api-01-int.cloudkeep.io:9311/v1/test_tenant/secrets/cc9d7a05-4d48-454b-8578-51decb84a8d9
         name: mysecret
         created: 2013-09-11 05:58:31.142398+00:00
         status: ACTIVE
         content types: {u'default': u'text/plain'}
         algorithm: aes
         bit length: 256
         mode: cbc
         expiration: None

Now, let's get the raw secret.

$ keep secret get --decrypt http://api-01-int.cloudkeep.io:9311/v1/test_tenant/secrets/cc9d7a05-4d48-454b-8578-51decb84a8d9
top secret data

delete

We will now delete the secret we've just created using its URI.

$ keep secret delete http://api-01-int.cloudkeep.io:9311/v1/test_tenant/secrets/cc9d7a05-4d48-454b-8578-51decb84a8d9

list

The list operation displays 10 items by default, and the limit can be adjusted. The maximum limit is 100, and there is an offset option that allows for the listing of different "pages".

$ keep secret list -l 2
Secret - href: http://localhost:9311/v1/test_tenant/secrets/49496a6d-c674-4384-b208-7cf4988f84ee
         name: super secret key
         created: 2013-09-04 15:39:22.572222+00:00
         status: ACTIVE
         content types: {u'default': u'text/plain'}
         algorithm: None
         bit length: None
         mode: None
         expiration: None

Secret - href: http://localhost:9311/v1/test_tenant/secrets/537b9d7a-878b-4c6a-a481-c7f46f102e46
         name: ordered secret
         created: 2013-09-04 16:28:27.763868+00:00
         status: ACTIVE
         content types: {u'default': u'application/octet-stream'}
         algorithm: aes
         bit length: 256
         mode: cbc
         expiration: None

$ keep secret list -l 2 -o 2
Secret - href: http://localhost:9311/v1/test_tenant/secrets/7c59986b-bdee-4258-a4a9-a8d9611fa6ec
         name: 7c59986b-bdee-4258-a4a9-a8d9611fa6ec
         created: 2013-09-04 20:58:48.579036+00:00
         status: ACTIVE
         content types: {u'default': u'application/octet-stream'}
         algorithm: aes
         bit length: 256
         mode: cbc
         expiration: None

Secret - href: http://localhost:9311/v1/test_tenant/secrets/5b583d73-8fc7-45b0-ad9b-319376486881
         name: min key
         created: 2013-09-05 18:05:24.981864+00:00
         status: ACTIVE
         content types: {u'default': u'text/plain'}
         algorithm: None
         bit length: None
         mode: None
         expiration: None