OpenStack API v1.0 Barbican This document is intended for software developers who want to programmatically manage orders and secrets using the Barbican API. 2013-12-12 Created initial outline 2014-04-08 Update after technical edit Getting Started Guide keep 10 This version of the Getting Started replaces and obsoletes all previous versions. The most recent changes are described in the table below: Barbican is a REST API that enables secure life-cycle management of keys and credentials, called secrets in this document, on behalf of customers. This is especially important for customers who want to securely store and retrieve credentials systematically. Barbican also enables customers to have keys generated on their behalf based on their requested encryption algorithm and bit length. This document provides an introduction into the Barbican API and explains how to perform basic API calls. Chapter 2 provides an overview of Barbican and lists the service endpoints that are available for the API. Chapter 3 shows you how to send requests to the API. Chapter 4 explains how to generate an authentication token. Chapter 5 shows you how to make API calls by using cURL. It provides examples of how to create and retrieve secrets and orders.

Barbican is a REST API designed for the secure storage and management of secrets through the Secrets resource. Barbican supports the following types of secrets.

Secret Types Supported by Barbican

Secret type	Description
Symmetric keys	Symmetric keys perform reversible encryption of data at rest, typically by using the AES algorithm set. Symmetric keys are required to enable features, such as encrypted Cloud Object Storage containers and Cloud Block Storage volumes, encrypted Cloud Backups, and so on.
Asymmetric keys	Asymmetric key pairs (sometimes referred to as public and private keys) are used in many scenarios where communication between untrusted parties is necessary. The most common case is with SSL/TLS certificates. Asymmetric keys are also used in solutions like SSH keys, S/MIME (mail) encryption, and digital signatures.
Raw secrets	Barbican stores raw secrets as binary blocks of data that are encrypted. Customers can use the API to store any secrets in any format that they want.

Barbican also supports the concept of orders. The Orders resource enables you to specify parameters, including an encryption algorithm and bit length, which are used to generate a random key. The Secrets resource is used for storage of secret data that has already been created.

To run the examples in this guide, you must have the following: An account for the OpenStack service you want to use A username and password, as specified during registration Prior knowledge of HTTP/1.1 conventions Basic familiarity with Cloud and RESTful APIs cURL, a command-line tool for transferring data with URL syntax. cURL is available for download from: http://curl.haxx.se/.

You have several options for sending requests through an API: Developers and testers might prefer to use cURL, the command-line tool from http://curl.haxx.se/. With cURL, you can send HTTP requests and receive responses back from the command line. If you prefer using a graphical interface, the REST client for Mozilla Firefox also works well for testing and trying out commands. See https://addons.mozilla.org/en-US/firefox/addon/restclient/. You can download and install RESTclient, a Java application used to test RESTful web services, from http://code.google.com/p/rest-client/.

cURL is a command-line tool that is available in most UNIX system-based environments and Apple Mac OS X systems, and can be downloaded for Microsoft Windows to interact with REST interfaces. For more information about cURL, visit http://curl.haxx.se/. cURL enables you to transmit and receive HTTP requests and responses from the command line or from within a shell script. As a result, you can work with the REST API directly without using one of the client APIs. The following cURL command-line options are used in this guide to run the examples.

cURL command-line options

Option	Description
-d DATA	Sends the specified data in a POST request to the HTTP server
-i HEADER	Includes the HTTP header in the output.
-H HEADER	Specifies an HTTP header in the request.
-X METHOD	Specifies the request method to use when communicating with the HTTP server. The specified request is used instead of the default method, which is GET. For example, -X PUT specifies to use the PUT request method.

If you Python installed on your computer, you can run the cURL JSON request examples with the following options to format the output from cURL: <curl JSON request example> | python -mjson.tool. To run the cURL request examples shown in this guide on Linux or Mac systems, perform the following actions: Copy each example from the HTML version of this guide an paste it into a text editor (for example, vi or TextEdit). Modify each example with your required account information and other information, as detailed in this guide. The carriage returns in the cURL request examples that are part of the cURL syntax are escaped with a backslash (\) to avoid prematurely terminating the command. However, you should not escape carriage returns inside the JSON message within the command. After you are finished modifying the text for the cURL request example with your information (for example yourUserName and yourApiKey), paste it into your terminal window. If you have trouble copying and pasting the examples as described, try typing the entire example on one long line, removing all the backslash line-continuation characters. Press Enter to run the cURL command.

To authenticate access to OpenStack services, you must first issue an authentication request to OpenStack Identity to acquire an authentication token. To request an authentication token, you must supply a payload of credentials in the authentication request. Credentials are usually a combination of your user name and password, and optionally, the name or ID of the project in which your cloud runs. Ask your cloud administrator for your user name, password, and project so that you can generate authentication tokens. When you send API requests, you include the token in the X-Auth-Token header. If you access multiple OpenStack services, you must get a token for each service. A token is valid for a limited time before it expires. A token can also become invalid for other reasons. For example, if the roles for a user change, existing tokens for that user are invalid. curl -i 'http://endpointURL/v2.0/tokens' -X 'POST' \ -d '{"auth":{"tenantName": "admin", "passwordCredentials: {"username":"admin", "password":"devstack"}}}' \ -H "Accept: application/json" -H "Content-Type: application/json" | python -m json.tool If the request succeeds, you receive a 200 OK response followed by a response body that contains a token in the form id is returned with an expires attribute that specifies when the token expires. The following example shows the portion of an authentication response in JSON that contains the authentication token: { "access":{ "token":{ "issued_at":"2013-11-06T20:06:24.113908", "expires":"2013-11-07T20:06:24Z", "id":"{token}", "tenant":{ "description":null, "enabled":true, "id":"604bbe45ac7143a79e14f3158df67091", "name":"admin" } }, } After authentication, you can use cURL to perform GET and POST requests for the Barbican API. For more information about authentication in OpenStack, see the Authenticate section in the OpenStack API QuickStart guide. This chapter explains how to use the Barbican API to do the following: Create an order to store a secret Store a secret Retrieve secret metadata Retrieve a secret Retrieve multiple secrets Retrieve multiple orders

You use the orders resource to store a secret. The ordering object encapsulates the workflow and history for the creation of a secret. To create an order that stores a secret, complete the following steps: Upload a plain-text order by submitting a POST request at a command-line interface, as shown in the following example: If the call is successful, you will receive a response like the following one: {"order_ref": "https://endpointURL/v1/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc"} Record the order ID that is returned in the response (in the example, 62d57f53-ecfe-4ae4-87bd-fab2f24e29bc). You will use this ID for the next request. Retrieve the order by typing the following command: curl -H 'Accept: text/plain' -H 'X-Project-Id:12345' <http://endpointURL/v1/orders/orderID If the call is successful, it will return a response like the following one: Record the secret ID that is returned in the response (in this example, 6c3ccd7d-46b6-4ece-9a58-a1be26b2758a).

You can submit a GET request to retrieve the status of an order. An order can have one of the following statuses: ACTIVE, PENDING, or ERROR. To retrieve the order status, type the following command: curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://endpointURL/v1/orders/orderID The following example shows an order with an ACTIVE status: { "status": "ACTIVE", "secret_ref": "endpointURL/v1/secrets/8a78d5e4-524a-4e81-96cc-c7d16ed85515", "updated": "2014-04-02T14:52:26.987458", "created": "2014-04-02T14:52:26.921043", "secret": { "name": "secretname", "algorithm": "aes", "payload_content_type": "application/octet-stream", "expiration": null, "bit_length": 256, "mode": "cbc" }, "order_ref": "https://endpointURL/v1/orders/b63d2c05-5d53-4db6-af06-4e388044deb8" }The following example shows an order with the status set to PENDING. Note that a secret ID is not returned, but in its place is a series of question marks. { "status": "PENDING", "secret_ref": "endpointURL/v1/secrets/????", "updated": "2014-03-19T22:40:06.720872", "created": "2014-03-19T22:40:06.720860", "secret": { "name": "secretname", "algorithm": "aes", "payload_content_type": "application/octet-stream", "expiration": null, "bit_length": 256, "mode": "cbc" }, "order_ref": "https://endpointURL/v1/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0" }

You can store a secret by submitting a POST request against the secrets resource and include the secret in the payload parameter. You specify the secret payload type in the payload_content_type parameter: For texts-based secrets, set the payload_content_type parameter to text/plain. For binary secrets, set the payload_content_type parameter to application/octet-stream. Submitting a POST request creates secret metadata. If the payload is provided with the POST request, then it is encrypted and stored, and then linked with this metadata. If no payload is included with the POST request, it must be provided with a subsequent PUT request. The secret resource encrypts and stores client-provided secret information and metadata. In contrast, the orders resource generats actual secret information on behalf of clients. The following example shows how to store a secret in the format of an AES key by submitting a POST request wth the base64-encoded secret payload specified against the secrets resource. If the request is successful, you will receive a response like the following: "secret_ref": "https://endpointURL/v1/secrets/a8957047-16c6-4b05-ac57-8621edd0e9ee" The example above shows the secretId, which will be returned in a successful response. You can also store a secret by first submitting a POST request without specifying the secret payload and then submitting a subsequent PUT request with the payload. This storage mode enables you to upload a binary file to the Barbican database directly for encrypted storage. For more information, read Two-step call flow for binary secrets.

After you have stored a secret, you can submit a GET request to retrieve either the secret metadata or the actual decrypted secret, depending on the Accept header that is provided in the GET request. For more information on different possibilities and combinations for setting the Accept header, read Examples of secret combinations. The following example shows how to retrieve secret metadata by submitting a GET request against the endpoint URL with the tenantID and secretID parameters specified and the Accept header set to application/json. curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://endpointURL/v1/secrets/secretID If the call is successful, you receive a response like the following: To retrieve the decrypted secret information, set the Accept header to either application/octet-stream for binary secrets or to text/plain for text-based secrets.

You can retrieve a list of secrets that are associated with a given project by typing the following command: curl -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Project-Id:12345' https://endpointURL/v1/secrets If the call is successful, you receive a response like the following one:{ "secrets": [ { "status": "ACTIVE", "secret_ref": "https://endpointURL/v1/secrets/9150d09b-7791-4c2a-90cc-1592e2ff67ac", "updated": "2014-03-19T22:39:55.136579", "name": "aes_key", "algorithm": "aes", "created": "2014-03-19T22:39:55.136567", "content_types": { "default": "application/octet-stream" }, "mode": "CDC", "bit_length": 256, "expiration": null }, { "status": "ACTIVE", "secret_ref": "https://endpointURL/v1/secrets/2e21bffa-2b81-432a-9bcb-2533593bcd34", "updated": "2014-03-19T22:39:56.018075", "name": "aes_key", "algorithm": "aes", "created": "2014-03-19T22:39:56.018061", "content_types": { "default": "application/octet-stream" }, "mode": "CDC", "bit_length": 256, "expiration": null }, { "status": "ACTIVE", "secret_ref": "https://endpointURL/v1/secrets/54bf3411-0765-467c-ba76-ba96c527e990", "updated": "2014-03-19T22:40:17.100402", "name": "secretname", "algorithm": "aes", "created": "2014-03-19T22:40:17.100389", "content_types": { "default": "application/octet-stream" }, "mode": "cbc", "bit_length": 256, "expiration": null } ], "total": 84, "next": "https://endpointURL/v1/secrets?limit=10&offset=10" }

You can use a single GET request to retrieve metadata for multiple orders for a given project. To do so, type the following command: curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://endpointURL/v1/orders If the call is successful, you receive a response like the following one:{ "total": 15, "orders": [ { "status": "PENDING", "secret_ref": "https://endpointURL/v1/secrets/????", "updated": "2014-03-19T22:40:06.720872", "created": "2014-03-19T22:40:06.720860", "secret": { "name": "secretname", "algorithm": "aes", "payload_content_type": "application/octet-stream", "expiration": null, "bit_length": 256, "mode": "cbc" }, "order_ref": "https://endpointURL/v1/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0" }, { "status": "PENDING", "secret_ref": "https://endpointURL/v1/secrets/????", "updated": "2014-03-19T22:41:18.930095", "created": "2014-03-19T22:41:18.930081", "secret": { "name": "secretname", "algorithm": "aes", "payload_content_type": "application/octet-stream", "expiration": null, "bit_length": 256, "mode": "cbc" }, "order_ref": "https://endpointURL/v1/orders/50212509-9c87-4a71-be3e-9ad59c290ede" }, { "status": "ACTIVE", "secret_ref": "https://endpointURL/v1/secrets/6e0bfe9f-8a59-4e29-81af-ea57eec96f28", "updated": "2014-03-25T16:42:20.584453", "created": "2014-03-25T16:42:20.430822", "secret": { "name": "secretname", "algorithm": "aes", "payload_content_type": "application/octet-stream", "expiration": null, "bit_length": 256, "mode": "cbc" }, "order_ref": "https://endpointURL/v1/orders/488cd596-f1a6-4abe-8cb0-16608f5b0359" } ], "next": "https://endpointURL/v1/orders?limit=10&offset=10" }

You can use a two-step secret storage process when secret data cannot be easily provided inside the JSON data in a one-step secret storage. To follow the two-step process, first create the secret metadata in Barbican by sending a POST request as shown in the following example: curl -i -H 'Content-Type: application/json' -H 'X-Project-Id:12345' -d '{"name": "Binary Key File"}' http://endpointURL/v1/secrets If the call is successful, you receive a 201 Created response as shown in the following example: HTTP/1.1 201 Created Content-Length: 93 Content-Type: application/json; charset=utf-8 Location: http://endpointURL/secrets/a83018d1-e657-4957-9ddd-42a479753e6b x-openstack-request-id: req-ea090bd4-5bfc-47ae-a388-746485d947f1 { "secret_ref": "http://endpointURL/v1/secrets/a83018d1-e657-4957-9ddd-42a479753e6b" } The secret metadata is now stored in Barbican. You still need to provide the actual secret, therefore be sure to save the secret_ref information as you will need it for uploading the secret data. Next, create a file with random data to be used as a secret key file. The following command creates a 5KB file that contains random data in the current directory: dd if=/dev/random of=secret_key_file count=5 bs=1024 Next, submit a PUT request that includes the secret key file you just created as sghown in the following example: curl -i -X PUT -H 'Content-Type: application/octet-stream' -H 'X-Project-Id:12345' \ -T ./secret_key_file http://endpointURL/v1/secrets/a83018d1-e657-4957-9ddd-42a479753e6b Barbican encrypts and stores the secret key file, associates it with the previously created metadata, and responds with an empty 200 OK message as shown in the following example: HTTP/1.1 200 OK Content-Length: 0 x-openstack-request-id: req-ab107dce-adfd-4b8d-b9eb-7095f8cf9b15 Now you can use a GET request to retrieve the secret, as explained in Retrieving a secret.

To learn more details about the Barbican API, read the Barbican API Developer Guide.