347a325833
Partially implements: blueprint replace-concept-of-tenants-for-projects Change-Id: I54f36c5a19488c4af5dfa67550b3d822922b4bb9
832 lines
41 KiB
XML
832 lines
41 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<book xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0"
|
|
xml:id="ck-gettingstarted">
|
|
<?rax canonical.url.base="http://docs.rackspace.com/keep/api/v1.0/ck-gettingstarted/content"?>
|
|
<title>Barbican Getting Started Guide</title>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>OpenStack</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<releaseinfo>API v1.0</releaseinfo>
|
|
<productname>Barbican</productname>
|
|
<pubdate/>
|
|
<abstract>
|
|
<para>This document is intended for software developers
|
|
who want to programmatically manage orders and secrets
|
|
using the Barbican API.</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<date>2013-12-12</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Created initial outline</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-04-08</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Update after technical edit</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
<raxm:metadata
|
|
xmlns:raxm="http://docs.rackspace.com/api/metadata">
|
|
<raxm:displayname>Getting Started Guide</raxm:displayname>
|
|
<raxm:product version="v1.0">keep</raxm:product>
|
|
<raxm:priority>10</raxm:priority>
|
|
</raxm:metadata>
|
|
</info>
|
|
<chapter xml:id="Feeds_Doc_Change_History">
|
|
<title>Document Change History</title>
|
|
<para>This version of the Getting Started replaces and
|
|
obsoletes all previous versions. The most recent changes
|
|
are described in the table below:</para>
|
|
<?rax revhistory?>
|
|
</chapter>
|
|
<chapter xml:id="Barbican_Overview">
|
|
<title>Barbican API Overview</title>
|
|
<para>Barbican is a REST API that enables secure life-cycle
|
|
management of keys and credentials, called <emphasis
|
|
role="italic">secrets</emphasis> 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. </para>
|
|
<para>This document provides an introduction into the Barbican
|
|
API and explains how to perform basic API calls. </para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Chapter 2 provides an overview of Barbican
|
|
and lists the service endpoints that are
|
|
available for the API.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Chapter 3 shows you how to send requests to
|
|
the API.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Chapter 4 explains how to generate an
|
|
authentication token.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Chapter 5 shows you how to make API calls by
|
|
using cURL. It provides examples of how to
|
|
create and retrieve secrets and orders.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section xml:id="What_is_Barbican">
|
|
<title>What is Barbican?</title>
|
|
<para>Barbican is a REST API designed for the secure
|
|
storage and management of <emphasis role="italic"
|
|
>secrets</emphasis> through the Secrets resource.
|
|
Barbican supports the following types of
|
|
secrets.</para>
|
|
<para>
|
|
<table>
|
|
<caption>Secret Types Supported by
|
|
Barbican</caption>
|
|
<col width="30%"/>
|
|
<col width="70%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Secret type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Symmetric keys</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Asymmetric keys</td>
|
|
<td>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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Raw secrets</td>
|
|
<td>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.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</para>
|
|
<para>Barbican also supports the concept of <emphasis
|
|
role="italic">orders</emphasis>. 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.</para>
|
|
</section>
|
|
<section xml:id="Prerequisites_Examples">
|
|
<title>Prerequisites for running examples</title>
|
|
<para>To run the examples in this guide, you must have the
|
|
following: <itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>An account for the OpenStack service you
|
|
want to use</para>
|
|
</listitem>
|
|
<listitem xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<para>A username and password, as specified
|
|
during registration</para>
|
|
</listitem>
|
|
<listitem xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<para>Prior knowledge of HTTP/1.1
|
|
conventions</para>
|
|
</listitem>
|
|
<listitem xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:html="http://www.w3.org/1999/xhtml">
|
|
<para>Basic familiarity with Cloud and RESTful
|
|
APIs</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>cURL, a command-line tool for
|
|
transferring data with URL syntax. cURL is
|
|
available for download from: <link
|
|
xlink:href="http://curl.haxx.se"
|
|
>http://curl.haxx.se/</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Feeds_Sending_API_Requests">
|
|
<title>Sending requests to the API</title>
|
|
<para>You have several options for sending requests through an
|
|
API: </para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Developers and testers might prefer to use cURL,
|
|
the command-line tool from <link
|
|
xlink:href="http://curl.haxx.se/"
|
|
>http://curl.haxx.se/</link>. </para>
|
|
<para>With cURL, you can send HTTP requests and
|
|
receive responses back from the command line.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you prefer using a graphical interface, the
|
|
REST client for Mozilla Firefox also works well
|
|
for testing and trying out commands. See <link
|
|
xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
|
|
>https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can download and install RESTclient, a Java
|
|
application used to test RESTful web services,
|
|
from <link
|
|
xlink:href="http://code.google.com/p/rest-client/"
|
|
>http://code.google.com/p/rest-client/</link>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<section xml:id="Feeds_using-curl-cli">
|
|
<title>Sending API requests using cURL</title>
|
|
<para>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 <link
|
|
xlink:href="http://curl.haxx.se/"
|
|
>http://curl.haxx.se/</link>. </para>
|
|
<para>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. </para>
|
|
<para>The following cURL command-line options are used in
|
|
this guide to run the examples.</para>
|
|
<para>
|
|
<table>
|
|
<caption>cURL command-line options</caption>
|
|
<col width="31%"/>
|
|
<col width="69%"/>
|
|
<thead>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><option>-d DATA</option></td>
|
|
<td>Sends the specified data in a POST
|
|
request to the HTTP server</td>
|
|
</tr>
|
|
<tr>
|
|
<td><option>-i HEADER</option></td>
|
|
<td>Includes the HTTP header in the
|
|
output.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><option>-H HEADER</option></td>
|
|
<td>Specifies an HTTP header in the
|
|
request.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><option>-X METHOD</option></td>
|
|
<td>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, <option>-X
|
|
PUT</option> specifies to use the
|
|
PUT request method.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>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: <emphasis role="bold"
|
|
><curl JSON request example> |
|
|
python -mjson.tool</emphasis>.</para>
|
|
</note>
|
|
</para>
|
|
<para>To run the cURL request examples shown in this guide
|
|
on Linux or Mac systems, perform the following
|
|
actions:</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para> Copy each example from the HTML version
|
|
of this guide an paste it into a text
|
|
editor (for example, vi or TextEdit).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> Modify each example with your required
|
|
account information and other information,
|
|
as detailed in this guide.</para>
|
|
<para>
|
|
<note>
|
|
<para>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.</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>After you are finished modifying the
|
|
text for the cURL request example with
|
|
your information (for example <emphasis
|
|
role="italic">yourUserName</emphasis>
|
|
and <emphasis role="italic"
|
|
>yourApiKey</emphasis>), paste it into
|
|
your terminal window. </para>
|
|
<para>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.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Press <guilabel>Enter</guilabel> to run
|
|
the cURL command.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Generating_Auth_Token">
|
|
<title>Generating an authentication token</title>
|
|
<para>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.</para>
|
|
<para>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. </para>
|
|
<para>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.</para>
|
|
<example>
|
|
<title>cURL Authenticate Request: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<screen language="bash">curl -i 'http://<replaceable>endpointURL</replaceable>/v2.0/tokens' -X 'POST' \
|
|
-d '{"auth":{"tenantName": "<replaceable>admin</replaceable>",
|
|
"passwordCredentials:
|
|
{"username":"<replaceable>admin</replaceable>",
|
|
"password":"<replaceable>devstack</replaceable>"}}}' \
|
|
-H "Accept: application/json"
|
|
-H "Content-Type:
|
|
application/json" | python -m json.tool </screen>
|
|
</example>
|
|
<para>If the request succeeds, you receive a 200 OK response
|
|
followed by a response body that contains a token in the
|
|
form <code>id</code> is returned with an
|
|
<code>expires</code> attribute that specifies when the
|
|
token expires. </para>
|
|
<para>The following example shows the portion of an
|
|
authentication response in JSON that contains the
|
|
authentication token:</para>
|
|
<para>
|
|
<example>
|
|
<title>cURL Authenticate Response: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<screen language="bash">{
|
|
"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"
|
|
}
|
|
},
|
|
} </screen>
|
|
</example>
|
|
</para>
|
|
<para>After authentication, you can use cURL to perform
|
|
<command>GET</command> and <command>POST</command>
|
|
requests for the Barbican API.</para>
|
|
<para>For more information about authentication in OpenStack,
|
|
see the <link
|
|
xlink:href="http://docs.openstack.org/api/quick-start/content/index.html"
|
|
>Authenticate</link> section in the <emphasis
|
|
role="bold">OpenStack API QuickStart</emphasis>
|
|
guide.</para>
|
|
</chapter>
|
|
<chapter xml:id="Use_Barbican_API">
|
|
<title>Using the Barbican API</title>
|
|
<para>This chapter explains how to use the Barbican API to do
|
|
the following:</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Create an order to store a secret</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Store a secret</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve secret metadata</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve a secret</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve multiple secrets</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve multiple orders</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section xml:id="Create_a_Secret">
|
|
<title>Creating an order to store a secret</title>
|
|
<para>You use the orders resource to store a secret. The
|
|
ordering object encapsulates the workflow and history
|
|
for the creation of a secret. </para>
|
|
<para>To create an order that stores a secret, complete
|
|
the following steps:</para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Upload a plain-text order by submitting
|
|
a <command>POST</command> request at a
|
|
command-line interface, as shown in the
|
|
following example:</para>
|
|
<para>
|
|
<example>
|
|
<title>Uploading an Order JSON Request
|
|
Example</title>
|
|
<programlisting language="json"><xi:include href="./samples/reqCreateOrder.json" parse="text"/></programlisting>
|
|
</example>
|
|
</para>
|
|
<para>If the call is successful, you will
|
|
receive a response like the following
|
|
one:</para>
|
|
<para>
|
|
<programlisting> {"order_ref":
|
|
"https://<replaceable>endpointURL</replaceable>/v1/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc"} </programlisting>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve the order by typing the
|
|
following command:</para>
|
|
<para>
|
|
<programlisting>curl -H 'Accept: text/plain' -H 'X-Project-Id:12345' <http://<replaceable>endpointURL</replaceable>/v1/orders/<replaceable>orderID</replaceable></programlisting>
|
|
</para>
|
|
<para>If the call is successful, it will
|
|
return a response like the following
|
|
one:</para>
|
|
<para>
|
|
<programlisting language="json"><xi:include href="./samples/resCreateSecret.json" parse="text"/></programlisting>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Record the secret ID that is returned in
|
|
the response (in this example,
|
|
6c3ccd7d-46b6-4ece-9a58-a1be26b2758a).
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Retrieve_Order_Status">
|
|
<title>Retrieving order status</title>
|
|
<para>You can submit a <command>GET</command> request to
|
|
retrieve the status of an order. An order can have one
|
|
of the following statuses: ACTIVE, PENDING, or ERROR. </para>
|
|
<para>To retrieve the order status, type the following
|
|
command:</para>
|
|
<para>
|
|
<programlisting>curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://<replaceable>endpointURL</replaceable>/v1/orders/<replaceable>orderID</replaceable></programlisting>
|
|
</para>
|
|
<para>The following example shows an order with an ACTIVE status:
|
|
<programlisting>{
|
|
"status": "ACTIVE",
|
|
"secret_ref": "<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/orders/b63d2c05-5d53-4db6-af06-4e388044deb8"
|
|
}</programlisting>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.</para>
|
|
<para>
|
|
<programlisting>{
|
|
"status": "PENDING",
|
|
"secret_ref": "<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0"
|
|
}</programlisting>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Store_a_Secret">
|
|
<title>Storing a secret</title>
|
|
<para>You can store a secret by submitting a
|
|
<command>POST</command> request against the
|
|
secrets resource and include the secret in the
|
|
<replaceable>payload</replaceable> parameter. You
|
|
specify the secret payload type in the
|
|
<parameter>payload_content_type</parameter>
|
|
parameter:</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>For texts-based secrets, set the
|
|
<parameter>payload_content_type</parameter>
|
|
parameter to
|
|
<code>text/plain</code>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>For binary secrets, set the
|
|
<parameter>payload_content_type</parameter>
|
|
parameter to
|
|
<code>application/octet-stream</code>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>Submitting a <command>POST</command> request
|
|
creates secret <emphasis role="italic"
|
|
>metadata</emphasis>. If the payload is
|
|
provided with the <command>POST</command>
|
|
request, then it is encrypted and stored, and
|
|
then linked with this metadata. If no payload
|
|
is included with the <command>POST</command>
|
|
request, it must be provided with a subsequent
|
|
<command>PUT</command> 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.</para>
|
|
</note>
|
|
</para>
|
|
<para>The following example shows how to store a secret in
|
|
the format of an AES key by submitting a
|
|
<command>POST</command> request wth the
|
|
base64-encoded secret payload specified against the
|
|
secrets resource.</para>
|
|
<para>
|
|
<programlisting language="json"><xi:include href="./samples/reqCreateSecret.json" parse="text"/></programlisting>
|
|
</para>
|
|
<para>If the request is successful, you will receive a response like the following:
|
|
<programlisting>
|
|
"secret_ref": "https://<replaceable>endpointURL</replaceable>/v1/secrets/a8957047-16c6-4b05-ac57-8621edd0e9ee"
|
|
</programlisting></para>
|
|
<para>The example above shows the <emphasis role="italic"
|
|
>secretId</emphasis>, which will be returned in a
|
|
successful response.</para>
|
|
<para>
|
|
<note>
|
|
<para xml:id="ck-devguide.xml">You can also store
|
|
a secret by first submitting a
|
|
<command>POST</command> request without
|
|
specifying the secret payload and then
|
|
submitting a subsequent <command>PUT</command>
|
|
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 <olink
|
|
targetdoc="ck-devguide"
|
|
targetptr="Two_Step_Binary_Secret">Two-step call flow for binary secrets</olink>.</para>
|
|
</note>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Retrieve_Secret">
|
|
<title>Retrieving a secret</title>
|
|
<para>After you have stored a secret, you can submit a <command>GET</command> request to
|
|
retrieve either the secret metadata or the actual decrypted secret, depending on the
|
|
<code>Accept</code> header that is provided in the <command>GET</command>
|
|
request. For more information on different possibilities and combinations for
|
|
setting the <code>Accept</code> header, read <olink targetdoc="ck-devguide"
|
|
targetptr="Examples_of_Secrets">Examples of secret combinations</olink>.</para>
|
|
<para>The following example shows how to retrieve secret
|
|
metadata by submitting a <command>GET</command>
|
|
request against the endpoint URL with the <emphasis
|
|
role="italic">tenantID</emphasis> and <emphasis
|
|
role="italic">secretID </emphasis> parameters
|
|
specified and the <code>Accept</code> header set to
|
|
<code>application/json</code>.</para>
|
|
<para>
|
|
<programlisting>curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://<replaceable>endpointURL</replaceable>/v1/secrets/<replaceable>secretID</replaceable></programlisting>
|
|
</para>
|
|
<para>If the call is successful, you receive a response
|
|
like the following: <programlisting language="json"><xi:include href="./samples/reqCreateSecretwithoutPayload.json" parse="text"/></programlisting>
|
|
<important>
|
|
<para>To retrieve the decrypted secret
|
|
information, set the <code>Accept</code>
|
|
header to either
|
|
<code>application/octet-stream</code> for
|
|
binary secrets or to <code>text/plain</code>
|
|
for text-based secrets. </para>
|
|
</important></para>
|
|
</section>
|
|
<section xml:id="Retrieve_multiple_secrets">
|
|
<title>Retrieving a list of stored secrets</title>
|
|
<para>You can retrieve a list of secrets that are
|
|
associated with a given project by typing the following
|
|
command:</para>
|
|
<para>
|
|
<programlisting>curl -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Project-Id:12345' https://<replaceable>endpointURL</replaceable>/v1/secrets</programlisting>
|
|
</para>
|
|
<para>If the call is successful, you receive a response like the following
|
|
one:<programlisting>{
|
|
"secrets": [
|
|
{
|
|
"status": "ACTIVE",
|
|
"secret_ref": "https://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/secrets?limit=10&offset=10"
|
|
}</programlisting>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Retrieve_Multiple_Orders">
|
|
<title>Retrieving a list of orders</title>
|
|
<para>You can use a single <command>GET</command> request
|
|
to retrieve metadata for multiple orders for a given
|
|
project. To do so, type the following command:</para>
|
|
<para>
|
|
<programlisting>curl -H 'Accept: application/json' -H 'X-Project-Id:12345' https://<replaceable>endpointURL</replaceable>/v1/orders </programlisting>
|
|
</para>
|
|
<para>If the call is successful, you receive a response like the following
|
|
one:<programlisting>{
|
|
"total": 15,
|
|
"orders": [
|
|
{
|
|
"status": "PENDING",
|
|
"secret_ref": "https://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0"
|
|
},
|
|
{
|
|
"status": "PENDING",
|
|
"secret_ref": "https://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/orders/50212509-9c87-4a71-be3e-9ad59c290ede"
|
|
},
|
|
{
|
|
"status": "ACTIVE",
|
|
"secret_ref": "https://<replaceable>endpointURL</replaceable>/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://<replaceable>endpointURL</replaceable>/v1/orders/488cd596-f1a6-4abe-8cb0-16608f5b0359"
|
|
}
|
|
],
|
|
"next": "https://<replaceable>endpointURL</replaceable>/v1/orders?limit=10&offset=10"
|
|
}</programlisting>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Two_step_secret_creation"><title>Creating a secret using two-step storage</title><para>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. </para>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>To follow the two-step process, first create the secret metadata in
|
|
Barbican by sending a <command>POST</command> request as shown in the
|
|
following example:</para>
|
|
<para>
|
|
<programlisting>curl -i -H 'Content-Type: application/json' -H 'X-Project-Id:12345' -d '{"name": "Binary Key File"}' http://<replaceable>endpointURL</replaceable>/v1/secrets</programlisting>
|
|
</para>
|
|
<para>If the call is successful, you receive a <code>201 Created</code>
|
|
response as shown in the following example:</para>
|
|
<para>
|
|
<programlisting>HTTP/1.1 201 Created
|
|
Content-Length: 93
|
|
Content-Type: application/json; charset=utf-8
|
|
Location: http://<replaceable>endpointURL</replaceable>/secrets/a83018d1-e657-4957-9ddd-42a479753e6b
|
|
x-openstack-request-id: req-ea090bd4-5bfc-47ae-a388-746485d947f1
|
|
|
|
{
|
|
"secret_ref": "http://<replaceable>endpointURL/</replaceable>v1/secrets/a83018d1-e657-4957-9ddd-42a479753e6b"
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>The secret metadata is now stored in Barbican. You
|
|
still need to provide the actual secret,
|
|
therefore be sure to save the
|
|
<code><parameter>secret_ref</parameter></code>
|
|
information as you will need it for
|
|
uploading the secret data.</para></listitem>
|
|
<listitem> <para>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:</para>
|
|
<para>
|
|
<programlisting>dd if=/dev/random of=secret_key_file count=5 bs=1024</programlisting>
|
|
</para></listitem>
|
|
<listitem><para>Next, submit a <command>PUT</command> request that includes the
|
|
secret key file you just created as sghown
|
|
in the following example:</para>
|
|
<para>
|
|
<programlisting>curl -i -X PUT -H 'Content-Type: application/octet-stream' -H 'X-Project-Id:12345' \
|
|
-T ./secret_key_file http://<replaceable>endpointURL</replaceable>/v1/secrets/a83018d1-e657-4957-9ddd-42a479753e6b
|
|
</programlisting>
|
|
</para></listitem>
|
|
<listitem><para>Barbican encrypts and stores the secret key file, associates it
|
|
with the previously created metadata, and
|
|
responds with an empty <code>200 OK</code>
|
|
message as shown in the following
|
|
example:</para>
|
|
<para>
|
|
<programlisting>HTTP/1.1 200 OK Content-Length: 0 x-openstack-request-id: req-ab107dce-adfd-4b8d-b9eb-7095f8cf9b15</programlisting>
|
|
</para></listitem>
|
|
</orderedlist></para>
|
|
<para>Now you can use a <command>GET</command> request to
|
|
retrieve the secret, as explained in <link
|
|
linkend="Retrieve_Secret">Retrieving a
|
|
secret.</link></para>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Barbican_Next_Steps">
|
|
<title>Next steps</title>
|
|
<para>To learn more details about the Barbican API, read the
|
|
Barbican API Developer Guide.</para>
|
|
</chapter>
|
|
</book>
|