diff --git a/docs/pom.xml b/docs/pom.xml index 947b1e762..bb2dec461 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -45,8 +45,7 @@ intranet constanze.kratel@RACKSPACE.COM - rackspace - 1 + builtforOpenStack true diff --git a/docs/src/docbkx/ck-devguide.xml b/docs/src/docbkx/ck-devguide.xml index d61113151..70a91b9a7 100644 --- a/docs/src/docbkx/ck-devguide.xml +++ b/docs/src/docbkx/ck-devguide.xml @@ -1,21 +1,15 @@ - + - Rackspace Barbican API Developer Guide + Barbican API Developer Guide - - 2012 - Rackspace US, Inc. - API v1.0 - Rackspace Barbican API + Barbican API + @@ -23,39 +17,47 @@ - Ipsum lorem. + Created initial draft - - - Copyright details are filled in by the build system. - - - - API Developer Guide - keep - 20 - + + API Developer Guide + keep + 20 + - - Preface + + Overview + 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.
Intended Audience This document is intended for software developers - interested in developing applications using the Rackspace - Barbican Application Programming Interface - (API). + interested in developing applications using the Barbican + Application Programming Interface (API). +
+
+ Additional resources + You can find additional information about Barbican at + https://github.com/openstack/barbican. For information about + OpenStack, refer to http://docs.openstack.org/.
- Document Change History + Document change history This version of the Developer Guide replaces and obsoletes all previous versions. The most recent changes are described in the table above. @@ -63,16 +65,12 @@
- - - Overview - - Barbican Core Concepts + Barbican core concepts
- Barbican Architecture + Barbican architecture The following diagram provides a visual overview of the Barbican API Architecture: @@ -80,46 +78,572 @@ Barbican API Architecture - + The Barbican API architecture consists of several API - node(s) which handle incoming REST requests to Barbican. These + nodes, which handle incoming REST requests to Barbican. These nodes can interact with the database directly if the request - can be completed synchronously (such as for GET requests), - otherwise the queue supports asynchronous processing by worker - nodes. - The latter could include interactions with third parties - such as certificate authorities. As implied in the diagram, - the architecture supports multiple API and worker nodes being - added/removed to/from the network, to support advanced - features such as auto scaling. Eventually, the database could - be replicated across data centers supporting region-agnostic - storage and retrieval of secured information, albeit with lags - possible during data synchronization. Also note that detailed - audit information will be written to the database as well, - capturing a history of actions that change the state of the - system. + can be completed synchronously, like in the case of + GET requests. Otherwise, the queue + supports asynchronous processing by worker nodes. + Asynchronous processing can include interactions with + third parties such as certificate authorities. Barbican + supports multiple API and worker nodes being added to or + removed from the network to support advanced features such as + auto scaling. +
+
+ Secrets resource + The secrets resource is the heart of the Barbican service. + It provides access to the secret and keying data that is stored + in the system. + The secret scheme represents the actual secret or key that + is presented to the application. Secrets can be of any + format, but additional functionality may be available for + known types of symmetric or asymmetric keys. The following + shows an example of a secret: + + { + "uuid": "e2b633c7-fda5-4be8-b42c-9a2c9280284d", + "name": "AES key", + "expiration": "2014-02-28T19:14:44.180394", + "secret": "b7990b786ee9659b43e6b1cd6136de07d9c5…", + "secret_type": "application/aes-256-cbc", +} + + A secret consists of the following elements: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Elements of a secret
ElementDescription
uuidUnique identifier for the secret. This value is + assigned by the API.
nameHuman readable name for the secret.
expirationThe expiration date for the secret in ISO-8601 + format. Once the secret has expired, it will no longer + be returned by the API or agent.
secretThe base64-encoded value of the secret.
secret_typeAn indication of the type of the file presenting the + secret.
+ + You can use one of the following methods to store a + secret: + + + + Submit a POST request against the + secrets resource and include the secret metadata in the + payload parameter. + + + Submit a POST request without a + payload parameter against the + secrets resource and then include the payload in a + subsequent PUT request. This mode + enables you to upload a a binary file to the Barbican + database directly for encrypted storage. + + + + + + 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. + + +
+ Examples of secret combinations + This section outlines the different request sequences + you can adhere to when storing secrets. Each sequence uses + different combinations for the content type and content encoding fields. The content type and + content encoding information is specified either in the + payload_content_type and + payload_content_encoding parameters + of a POST request or in the Accept + and Content-type headers of a GET + request. + The following request combinations are possible: + + + + One-step sequence to create and retrieve a secret + using UTF-8/ASCII format + + + One-step sequence to create and retrieve a secret + using binary format + + + Two-step sequence to create and retrieve a secret + using binary format + + + One-step sequence to create and retrieve a secret + using plain text format + + + +
+ One-step sequence for secrets using + UTF-8/ASCII + The following table shows the sequence for creating an + retrieving a secret using UTF-8/ASCII format. When you + submit the POST request, set the + payload_content_type parameter to + text/plain and do not specify a + payload_content_encoding + parameter. When you make the POST + request, the supplied payload will be encrypted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
One-Step UTF-8/ASCII Secret + Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretstext/plainMust be omittedThe supplied payload is encrypted
GET secretsapplication/json for + Accept headerNot required/ignoredReturns JSON metadata, with + content-types field set + to "default": "text/plain".
GET secretstext/plain for Accept + headerNot required/ignoredReturns the decrypted payload from the previous + request.
+ +
+
+ One-step sequence for binary secrets + The following table shows the one-step sequence for + creating an retrieving a secret using binary format. When + you submit the POST request, set the + payload_content_type parameter to + application/octet-stream and the + payload_content_encoding + parameter to base64. When you make the + POST request, the supplied payload + will be converted from base64 to binary format and then + encrypted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
One-Step Binary Secret Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretsapplication/octet-streambase64Supplied payload is converted from base64 to + binary, and then encrypted.
GET secretsapplication/json for + Accept headerNot required/ignoredJSON metadata, with the + content-types field set to + "default": + "application/octet-stream"
GET secretsapplication/octet-stream for + Accept headerNot specifiedPrevious payload is decrypted and returned as raw + binary, even if the POST request + provided data in base64 format.
+
+
+ Two-step sequence for binary secrets + The following table shows the two-step sequence for + creating an retrieving a secret using binary format. First + submit a POST request without specifying a payload and a + corresponding content type and content encoding. + Submitting a POST request without payload creates metadata + for the secret. To add payload information, submit a PUT + request with the secret id that was returned from the POST + request. and set the content type to application/octet + stream and the content encoding to base64, which converts + the payload from base64 to binary format and then encrypts + it. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Two-Step Binary Secret + Create/Retrieve
MethodContent TypeContent EncodingResult
POST secretsNot required/ignoredNot required/ignoredOnly metadata is created. If the + payload_content_type or + payload_content_encoding + parameters were provided, they are not used or + saved with the metadata. The + subsequentPUT request + determines the secret's content type.
PUT secrets, first option + with content encoding set to base64Content-Type header set to + application/octet-streamContent-Encoding header set to + base64Supplied request body is converted from + base64 to binary, then + encrypted.
PUT secrets, second option + as binaryContent-Type header set to + application/octet-streamNot specifiedSupplied request body is encrypted as is.
GET secrets (metadata)Accept header set to + application/jsonNot required/ignoredReturns JSON metadata, with + content-types field set + to "default": + "application/octet-stream"
GET secrets (decrypted)Accept header set to + application/octet-streamNot required/ignoredThe previous request is decrypted and returned + as raw binary.
+ +
+
+ Two-step sequence for plain text secrets + The following table shows the two-step sequence for + creating an retrieving a secret using binary format. First + submit a POST request without + specifying a payload and a corresponding content type and + content encoding. Submitting a POST + request without payload creates metadata for the secret. + To add payload information, submit a + PUT request with the secret id that + was returned from the POST request. and + set the content type to text/plain which + stores the payload as is. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Two-Step Plain-Text Secret + Create/Retrieve
ActionContent TypeContent EncodingResult
POSTNot required/ignoredNot required/ignoredOnly metadata is created. If the + payload_content_type or + payload_content_encoding + parameters were provided, they are not used or + saved with the metadata. The subsequent + PUT request specifies the + content format for the secret.
PUT Content-Type header is set to + text/plain.Not required/ignoredSupplied request body is encrypted as is.
GETAccept header is set to + application/json.Not required/ignoredReturns JSON metadata, with the + content-types field set + to "default": "text/plain"
GETAccept header is set to + text/plain.Not specifiedThe previous request is decrypted and returned + as UTF-8 text.
+ +
+
+
+
+ Orders + The orders resource allows for the generation of secret + material by Barbican. The ordering object encapsulates the + workflow and history for the creation of a secret. This + interface is implemented as an asynchronous process since the + time to generate a secret can vary depending on the type of + secret. + The following shows an example of an order: + + { + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/12345/secrets/0b759c30-8ed2-4c3e-ab7d-6320f9655e60", + "updated": "2014-05-02T18:02:44.381024", + "created": "2014-05-02T18:02:44.297474", + "secret": { + "name": "secretname", + "algorithm": "aes", + "payload_content_type": "application/octet-stream", + "expiration": null, + "bit_length": 256, + "mode": "cbc" + }, + "order_ref": "https://endpointURL/v1/12345/orders/18e3f713-ddf0-4c49-99c4-76794e65c870" +} + + An order consists of the following elements: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Elements of an order
ElementDescription
secretLists all the secret parameters provided in the + original order request.
order_refSpecifies the URI pointing to the order.
statusSpecifis the status of the order. Can be + PENDING, ACTIVE or + ERROR.
secret_refSpecifies the URI to the secret once it is generated. This + field is not available unless the status is + ACTIVE.
error_status_codeOptional. Specifies the HTTP-style status code of + the root cause error condition, only if the status is + ERROR.
error_reasonOptional. Provides details of the root cause of the + error, only if the status is ERROR.
+ +
+ Generating an order + This section describes how to generate an order throught + the Barbican API. + + + + Upload a plain-text order by submitting a + POST request at a command-line + interface, as shown in the following example: + + + Uploading an Order JSON Request + Example + + + + Make sure to have a payload specified, as well as + a corresponding content type and content + encoding. + If the call is successful, you will receive a + response like the following one: + + { + "order_ref": "https://endpointURL/v1/123456/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' <http://endpointURL/v1/tenantID/orders/orderID + + If the call is successful, it will return a + response like the following one: + + + + + + +
- General API Information + General API information
Authentication Retrieving the Authentication Token - Every REST request for Barbican requires the inclusion of - a specific authentication token, supplied by the - X-Auth-Token HTTP header. Customers obtain this - token by first using the Rackspace Cloud Identity service and - supplying a valid user name and API access key. + 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 tenant in + which your cloud runs. Ask your cloud administrator for your + user name, password, and tenant so that you can generate + authentication tokens. + When you send API requests, you include the token in the + X-Auth-Token HTTP 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.
- Retrieving the Authentication Token - The authenticate operation provides users with an + Retrieving the authentication token + The authenticate operation provides users with an authentication token and a list of regional cloud endpoints. The sample requests and responses in this section illustrate a general case. In your authentication request, use your own @@ -155,75 +679,18 @@ (503) Authentication Request for US Endpoint: JSON - - - - - - - - - + - - - The username supplied here is your - common Rackspace Cloud user name. - - - The key is your API access key. You can obtain the - key from the Rackspace - Cloud Control Panel in the <Your - Account>/API - Access section. - - Authentication Response for US Endpoint: JSON - - + + - - - - - - - - - - - - - - - - + + - - The information shown in the authentication response - example is for US-based accounts. If you authenticate - against the UK endpoint, the response you receive shows - the service catalog information for UK-based - accounts. - This token can be presented to a service as evidence @@ -232,8 +699,8 @@ The token's expires attribute denotes the time after which the token automatically becomes invalid. A token can be manually revoked before the time - identified by the expires attribute. - Theexpires attribute predicts a token's + identified by the expires attribute. The + expires attribute predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan. Users are encouraged to cache a token until it expires. @@ -242,112 +709,16 @@ re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint. - - The token's expiration time is formatted - differently in the US and UK. These response examples - show the US format. For examples of the UK format, see - http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/POST_authenticate_v2.0_tokens_.html. - - - - - Users can be assigned a default region. If multiple - endpoints are associated with a service in the user's - catalog, the endpoint for the user's default region is - selected if it is available. In this example, the user's - default region is DFW, and several of the services in - the user's catalog offer endpoints in that region and - the ORD region; whenever possible, the user's work is - directed to the DFW region. - - - - Users can be assigned multiple roles, with each role - providing specific privileges. In this example, - jsmith is the administrative user for the - account and holds the fully-privileged - identity:admin role. Other users might - hold other roles with different privileges. Roles are - not necessarily associated with actual job functions - such as Administrator, Operator, Developer, Tester, or - Trainer. - - - - The service catalog lists the services this user can - access. - - - Some services recognize the specification of a - tenant. If a service does recognize tenants, the format - of the tenant specification is defined only by the - service. For details about whether and how to specify a - tenant, check the documentation for the service that you - are using. - - - - An endpoint can be assigned public and internal - URLs. A public URL is accessible from anywhere. Access - to a public URL usually incurs traffic charges. Internal - URLs are accessible only to services within the same - region. Access to an internal URL is free of charge. - - - - A service can expose endpoints in different regions. - Regional endpoints allow users to provision resources in - a manner that provides high availability. - Some services are not region specific. These - services supply a single, non-regional endpoint and do - not provide access to internal URLs. - - - - The service name attribute identifies each unique - service in the catalog. After a service is created, its - name does not change. However, new services of the same - service type can be added to the catalog with new names. - - If you are programmatically parsing an - authentication response, use service type rather than - service name to determine whether a user has access to - a particular kind of service. Service type is stable - across all releases. New service types might be - developed, but existing service types are not renamed. - It is possible to subscribe to multiple services of - the same type. Whatever those services are named, you - can always recognize them by parsing for service type - in the authentication response's service catalog. - - - - - - The service type attribute identifies services that - perform similar functions, regardless of service names. - In this example, the service named cloudFiles is - identified as type="store", indicating that - it is a storage service even though the word "storage" - does not appear in its name. - - Use service type as the primary value for locating - a service. If multiple endpoints of the same service - type exist in the same region, use service name to - locate the appropriate service. - - + For more information about authentication in OpenStack, see the Authenticate section in the OpenStack API QuickStart guide.
Service Access Endpoints - Barbican s a regionalized service. The user of the service + Barbican is a regionalized service. The user of the service is therefore responsible for appropriate replication, caching, and overall maintenance of Barbican data across regional boundaries to other Barbian servers. @@ -374,31 +745,31 @@ Chicago (ORD) https://ord.secrets.api.rackspacecloud.com/v1.0/1234/ + >https://<endpoint>/v1.0/1234/ Dallas/Ft. Worth (DFW) https://dfw.secrets.api.rackspacecloud.com/v1.0/1234/ + >https://<endpoint>/v1.0/1234/ London (LON) - https://lon.secrets.api.rackspacecloud.com/v1.0/1234/ + https://<endpoint>/v1.0/1234/ Sydney (SYD) - https://syd.secrets.api.rackspacecloud.com/v1.0/1234/ + https://<endpoint>/v1.0/1234/ Hong Kong (HKG) https://hkg.secrets.api.rackspacecloud.com/v1.0/1234/ + >https://<endpoint>/v1.0/1234/ @@ -408,12 +779,10 @@ your actual Tenant ID. You will find your tenant Id after the final '/' in the publicURL field returned by the authentication - response. For example, in Example 2, - “Authentication Response for US Endpoint: JSON” the + response. For example, in Example 2, + “Authentication Response for US Endpoint: JSON” the publicURL field for secrets - ("https://ord.secrets.api.rackspacecloud.com/v1.0/1100111") shows that the tenant Id is 1100111.
@@ -430,7 +799,7 @@ guaranteed to be compatible with one another. Sample Request URL for Contract Version 1.0 - https://ord.secrets.api.rackspacecloud.com/v1.0/1234 + https://<endpoint>/v1.0/1234 This document pertains to contract version 1.0. @@ -439,15 +808,13 @@
- Request and Response Types - The Rackspace Barbican API supports JSON data - serialization formats. You specify the request format by using - the Content-Type header. The request format is + Request and response types + The Barbican API supports JSON data serialization formats. + You specify the request format by using the + Content-Type header. The request format is required for calls that have a request body. You can specify the response format in - requests either by using the Accept header or by - adding a .json extension to the request URI. JSON - is also used for the response format. + requests by using the Accept header. @@ -463,306 +830,21 @@ - + - - - - - -
Response Format
JSON application/json.json Yes
XMLapplication/xml.xmlNo
-
- Limits - All accounts, by default, have a preconfigured set of - thresholds (or limits) to manage capacity and prevent abuse of - the system. The system recognizes rate - limits and absolute - limits. Rate limits are thresholds that are - reset after a certain amount of time passes. Absolute limits - are fixed. -
- - Rate Limits - Rate limits are specified in terms of both a - human-readable wildcard URI and a machine-processable - regular expression. The regular expression boundary matcher - '^' takes effect after the root URI path. - For example, the regular expression - ^/v1.0/execute would match the bolded portion - of the following URI: - https://ord.secrets.api.rackspacecloud.com/v1.0/execute. - For any user, all operations are limited to 1,000 calls - per minute. - If you exceed the thresholds established for your - account, a 413 (Rate Control) HTTP - response is returned with a Retry-After header - to notify the client when it can attempt to try again. - -
-
- - - General API Information -
- Secrets Resource - The secrets resource is the heart of the Barbican service. - It provides access to the secret / keying material stored in - the system. - The secret scheme represents the actual secret or key that - will be presented to the application. Secrets can be of any - format, but additional functionality may be available for - known types of symmetric or asymmetric keys. The schema for - creating a secret differs from the retrieval schema is shown - next. - Secrets can be created in two ways: Via POST including a - payload, or with a POST without a payload followed by a PUT. - - - Note that the POST calls create secret metadata. If the payload is - provided with the POST call, then it is encrypted and - stored, and then linked with this metadata. Otherwise, the - PUT call provides this payload. Hence clients must provide - the secret information to store via these 'create' - operations. This should not be confused with the secret - 'generation' process via the orders resource below, - whereby Barbican generates the secret information. - - -
Examples of Secret Combinations - The tables in this section are focused on the - content-types and content-encodings of the various REST verb - flows, even though each flow might have a different way to - specify these values (either via http header settings or - JSON request field). The reason for this approach is that - while each flow has a different means to specify the - mime-type and encoding, the values set for them must still - be consistent with valid mime-type or encoding - selections. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
One-Step UTF-8/ACII Secret - Create/Retrieve
Actioncontent-typecontent-encodingResult
POST secretspayload_content_type = text/plainpayload_content_encoding not neededSupplied payload is encrypted
GET secrets (meta)Accept: application/jsonNot required/ignoredJSON metadata, with content-type set to - 'default':'text/plain'
GET SecretsAccept: text/plain Not required/ignoredPrevious payload is decrypted
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
One-Step Binary Secret Create/Retrieve
Actioncontent-typecontent-encodingResult
POST secretspayload_content_type = application/octet-streampayload_content_encoding = base64Supplied payload is converted from base64 to binary, - then encrypted
GET secrets (meta)Accept: application/jsonNot required/ignoredJSON metadata, with content-type set to - 'default':'application/octet-stream'
GET SecretsAccept: text/plain Not specifiedPrevious payload is decrypted and returned as raw - binary, even if the PUT request provided data in - base64.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Two-Step Binary Secret Create/Retrieve
Actioncontent-typecontent-encodingResult
POST secretspayload_content_type optionally specifiedpayload_content_encoding optionally specifiedOnly metadata is created. If the - payload_content_type or payload_content_encoding - fields were provided, they are not used or saved - with the metadata. The PUT request (next) will - determine the secret's content type
GET secrets (meta)Content-type: application/octet-streamContent-Encoding: base64Supplied request body is converted from base64 to binary, then - encrypted
GET SecretsContent-type: application/octet-streamNot specifiedSupplied request body is encrypted as is
POST secretsAccept: application/jsonNot required/ignoredJSON metadata, with Content-Types set to - 'default':'application/octet-stream'
POST secretsAccept: application/octet-streamNot specifiedPrevious request is decrypted and returned as raw - binary, even if the PUT - provided the data in base64.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Two-Step Plain-Text Secret - Create/Retrieve
Actioncontent-typecontent-encodingResult
POST secretspayload_content_type = optionally specifiedpayload_content_encoding optionally specifiedOnly metadata is created. If the - payload_content_type or payload_content_encoding - fields were provided, they are not used or saved - with the metadata. The PUT request (next) will - determine the secret's content format
PUT secretsContent-type: text/plain Not required/ignoredJSON metadata, with content-type set to - 'default':'text/plain'
GET secrets (meta)Accept: application/jsonNot required/ignoredJSON metadata, with Content-Types set to - 'default':'text/plain'
GET secrets (decrypted)Accept: text/plainNot specifiedPrevious request is decrypted and returned as - utf-8 text
- -
-
-
- Orders Resource - The orders resource allows for the generation of secret - material by Barbican. The ordering object encapsulates the - workflow and history for the creation of a secret. This - interface is implemented as an asynchronous process since the - time to generate a secret can vary depending on the type of - secret.
- - - API Operations + + API operations This chapter describes each of the operations. The following table summarizes all of the operations that are available: - + - diff --git a/docs/src/docbkx/ck-gettingstarted.xml b/docs/src/docbkx/ck-gettingstarted.xml index 7b65dfa8a..47cb302aa 100644 --- a/docs/src/docbkx/ck-gettingstarted.xml +++ b/docs/src/docbkx/ck-gettingstarted.xml @@ -4,7 +4,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ck-gettingstarted"> - Rackspace Barbican API Getting Started Guide + Barbican Getting Started Guide @@ -12,22 +12,12 @@ - Rackspace Cloud + OpenStack - - 2013 - Rackspace US, Inc. - API v1.0 - Rackspace Barbican + Barbican - - - Copyright details are filled in by the - template. - - This document is intended for software developers who want to programmatically manage orders and secrets @@ -44,6 +34,16 @@ + + 2014-04-08 + + + + Update after technical edit + + + + @@ -60,178 +60,163 @@ - Rackspace Barbican API Overview - Barbican is a REST API designed for the secure storage, - provisioning and management of secrets. + Barbican API Overview + 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. + + +
What is Barbican? Barbican is a REST API designed for the secure - storage, provisioning and management of secrets. + storage and management of secrets through the Secrets resource. Barbican supports the following types of - secrets: + secrets. - +
- + - - + + - + - - +
Secret Types Supported by Barbican
Secret TypeSecret type Description
Symmetric KeysPerform reversible encryption of data - at rest, typically using the AES - algorithm set. Symmetric keys are - required to enable features, such as - encrypted Swift containers and Cinder - volumes, encrypted Cloud Backups, - etc.Symmetric keysSymmetric 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 KeysAsymmetric keys Asymmetric key pairs (sometimes - referred to as public / private keys) - are used in many scenarios where + referred to as public and private + keys) are used in many scenarios where communication between untrusted - parties is desired. The most common + parties is necessary. The most common case is with SSL/TLS certificates. - Asymmetric keys but are also used in + Asymmetric keys are also used in solutions like SSH keys, S/MIME (mail) - encryption and digital + encryption, and digital signatures.
Raw SecretsBarbican stores secrets as binary - blocks of data (encrypted, naturally). - Clients can use the API to store any - secrets in any format they desire. + Raw secretsBarbican 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.
- Prerequisites for Running Examples - In order to run the examples in this guide, you must - have the following: + Prerequisites for running examples + To run the examples in this guide, you must have the + following: - A Rackspace Cloud account + 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 - A Rackspace Cloud username and password, - as specified during registration + cURL, a command-line tool for + transferring data with URL syntax. cURL is + available for download from: http://curl.haxx.se/.
-
- Service Access and Endpoints - The following table summarizes the endpoints to use - for your Cloud Feeds API calls. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Regionalized Service Endpoints
RegionEndpoint
Chicago (ORD)https://<tbd>
Dallas/Ft. Worth - (DFW)https://<tbd>
London (LON)https://<tbd>
Sydney (SYD) - https://<tbd>
Hong Kong (HKG) - <tbd>
Replace the sample account ID number, 1234, - with your actual account number returned as part of - the authentication response. Use your actual account - number wherever you see the field tenant id specified in this - guide. - - - - Choose the endpoint from the table for - the datacenter where your Cloud resources - are located. - - - The Cloud Server that you use must be - located in the same datacenter where your - database resides. - - - All examples in this guide assume that - you are operating against the DFW - datacenter, however if you are using a - different datacenter, be sure to use the - associated endpoint from the table above - instead. - - - -
- Send Requests to the API + Sending requests to the API You have several options for sending requests through an API: - Developers and testers may prefer to use cURL, + 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. + With cURL, you can send HTTP requests and + receive responses back from the command line. + - If you like to use a more graphical interface, - the ReST client for Firefox also works well for - testing and trying out commands, see 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 also download and install rest-client, a - Java application to test ReSTful web services, + You can download and install RESTclient, a Java + application used to test RESTful web services, from http://code.google.com/p/rest-client/. @@ -239,594 +224,621 @@
- Send API Requests Using cURL - cURL is a command-line tool that is available on - most UNIX®-like environments and Mac OS X® and can be - downloaded for Windows® in order to interact with the - ReST interfaces. For more information on cURL, visit - Sending API requests using cURL + 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 allows you to transmit and receive HTTP - requests and responses from the command-line or from - within a shell script. This makes it possible to work - with the ReST API directly without using one of the - client APIs. - The following cURL command-line options will be used - in this guide to run the examples: - - cURL Command-Line Options - - - - Sends the specified data in a post - request to the HTTP server. - - - - - - Includes the HTTP header in the - output. - - - - - - Specify an HTTP header in the - request. - - - - - - 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, - specifies to - use the PUT request method. - - - - - If you have the tools, 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. - -
- - - Generate an Authentication Token - You need to generate a token whether you use cURL or a - ReST client. - In order to use the ReST API, you will first need to - obtain an authentication token, which will need to be - passed in for each request using the - X-Auth-Token header. - The following example demonstrates how to use cURL to - obtain the authentication token and the account number. - You will need to supply the authentication token and - account number when making subsequent Cloud Databases API - calls. - Remember to replace the names in the Authenticate - Request examples below with their respective - values: - - your_username The username is - your common Rackspace Cloud username, as - supplied during registration. - - - your_api_key The key is your - API access key. - To find your API - Key: - - - Log in to the Cloud Control Panel - (https://mycloud.rackspace.com). - - - On the upper-right side of the top - navigation pane, click your - username. - - - From the menu, select - Account - Settings. - - - In the Login Details section of the - Account Settings page, locate the - API Key field - and click - Show. - - - Copy the value of the API Key and - paste it into a text editor of your - choice. - - - Click Hide to - hide the value of the API Key. - - - You also need your cloud account number. In - the documentation, the account number is often - referred to as your tenant name or tenant ID - (technically, the ID is different from the - name, but at Rackspace, they are the same - thing). Together, three components—your - username, your API Key, and your tenant ID or - cloud account number—form the authentication - credentials that are required to connect to - the Rackspace cloud. To find your tenant ID or - cloud account number, locate your username on - the upper-right side of the top navigation - pane in the Cloud Control Panel. The tenant ID - or account number is in parentheses just to - the right of your username. - - - Notice that you authenticate using a special URL for - Cloud authentication services. For example, you may use - https://identity.api.rackspacecloud.com/v2.0/tokens, - as shown in the following Authenticate Request examples. - Note that the v2.0 component in the URL - indicates that you are using version 2.0 of the Cloud Auth - API. - - cURL Authenticate Request: XML - - curl \ -'<?xml version="1.0" encoding="UTF-8"?> -<auth> - <apiKeyCredentials - xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0" - username="your_username" - apiKey="your_api_key"/> -</auth>' \ - \ - \ -'https://identity.api.rackspacecloud.com/v2.0/tokens' - - - cURL Authenticate Request: JSON - - curl \ -'{ - "auth": - { - "RAX-KSKEY:apiKeyCredentials": - { - "username": "your_username", - "apiKey": "your_api_key"} - } -}' \ - \ -'https://identity.api.rackspacecloud.com/v2.0/tokens' - - - For UK-based accounts, you may decide to use - 'https://lon.identity.api.rackspacecloud.com/v2.0/tokens' - instead. - - The authentication token id is returned - along with an expires attribute that - specifies when the token expires. - - - - For all response examples in this guide, the - field values you receive in your responses - will vary from those shown here since they - will be specific to your account. - - - The information shown in the Authenticate - Response examples above is for US-based - accounts. If you authenticate against the - UK-endpoint for auth, you will see the service - catalog information for UK-based - accounts. - - - The id attribute in the - Authenticate Response specifies the - authentication token. Tokens are valid for a - finite duration. - Remember to supply your authentication token - wherever you see the field your_auth_token in - the examples in this guide. - - - The expires attribute denotes - the time after which the token will - automatically become invalid. A token may be - manually revoked before the time identified by - the expires attribute; expires - predicts a token's maximum possible lifespan - but does not guarantee that it will reach that - lifespan. Clients are encouraged to cache a - token until it expires. - - - Applications should be designed to - re-authenticate after receiving a 401 - (Unauthorized) response from a service - endpoint. - - - - The publicURL endpoints for - cloudDatabases (for example - https://ord.databases.api.rackspacecloud.com/v1.0/1100111) - are also returned in the response. - You will find the actual account number after the final - '/' in the publicURL field. In this example, - you can see that the account number is 1100111. - - - Prepare your Workstation to Use Barbican - To prepare your workstation to use Barbican, you need to - have several tools and applications install on your - workstation. - The following table lists the tools that must be - installed prior to installing Barbican: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Prerequisites for installing - Barbican
ToolDescription
pyenv Python Version Management tool. Available - for download from GitHub.
pyenv-virtualenvpyenv plugin that provides a pyenv - virtualenv command to create virtualenv - for Python on UNIX-like systems. Available - for download from GitHub.
GitGit client. Available for download from - http://git-scm.com/downloads.
cURLCommand line tool for transferring data - with URL syntax. Available for download - from: http://curl.haxx.se/.
pipPython installer tool. Available for - download from: http://www.pip-installer.org/en/latest/installing.html.
 - For Unix distributions, you may also need to install the - python and sqlite3 development packages. The following - example shows how to install Python and Sqlite3 from Red - Hat distributions, such as CentOS: - sudo yum install python-devel -sudo yum install sqlite-devel The following example shows how to install Python and Sqlite3 - from Debian distributions, such as Ubuntu: - sudo apt-get install python-dev -sudo apt-get install libsqlite3-dev - To use Barbican for development and evaluation purposes, - it is recommended that you run Barbican from a virtual - environment. We recommend that you use pyenv virtual environment - framework because this framework works best with our - install script. - To install the pyenv - virtual environment framework, complete the following - steps: - - - - Install the pyenv tool by following the - installation instructions on GitHub that are - available from this link: https://github.com/yyuu/pyenv. - - - Install the pyenv-virtualenv plugin by - following the installation instructions on - Github that are available from this link: - https://github.com/yyuu/pyenv-virtualenv. - - - At a command-line interface run the - following command to install the latest - version of Python: - - - pyenv install 2.7.5 - - - - Type the following command to create the - Barbican virtual environment: - - - pyenv virtualenv 2.7.5 barbican27 - - - - To start the Barbican virtual environment, - type the following command: - - - pyenv shell barbican27 - - - - - - - Install Barbican - The Barbican source code is stored on Github. In order - to download the latest Barbican source code, you need to - make sure that you have Git installed on you - workstation. - To install Barbican, you need to complete the following - steps: - - - - Download the Barbican GitHub - repository - - - Install the Barbican application - server - - - Verify Barbican installation - - - -
Download Barbican GitHub RepositoryTo download the Barbican GitHub repository, complete the - following steps: + 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. - - - On your workstation, change to the - directory to which you want to download - Barbican. - - - Run the following command to create the - Barbican repository: - - git clone https://github.com/stackforge/barbican.git - - - Run the following command to change the - root of your local Barbican - repository: - - cd barbican - - -
-
Install Barbican Application ServerTo install the Barbican application server, type the following - at a command-line interface: - bin/barbican.sh install
-
- Verify Barbican - Installation - You can verify that you have successfully installed - Barbican by doing the following: - - - - At a command-line interface, type the - following: - - - curl localhost:9311 - - - If Barbican has installed successfully, - you should see a response that looks like - the following example: - - - {"v1": "current", "build": "2013.2.{build_id}"} - - - -
- - - Integration Environment - We have set up an insecure integration environment at http://iad-int-api.cloudkeep.io:9311 so that - you can try the Barbican API without having to install and - configure it first. - - - This endpoint is provided for evaluation - purposes only, with no attempt made to secure or - persist data stored therein. Therefore, please do - not store any data that is sensitive, critical or - that you otherwise care about. - - - - - Authentication is currently turnd off or the - integration environment. - - -
Obtaining a Barbican Version Resource - First, you need to generate a valid token on - keystone. The integration environment provides a - Keystone server at http://keystone-int.cloudkeep.io as - shown in the following example: - - If successful, this request will return the following response, - which contains the token information: - - From the response you need to record the following - two values: - - - - Token - id, which is - 39a8b7f62dcb4095a74a4e65a68c85d8 in the - example above. - - - Tenant - id, which is - 0239200f037f4520aadd9791fad19af8 in the - example above. - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cURL command-line options
OptionDescription
Sends the specified data in a POST + request to the HTTP server
Includes the HTTP header in the + output.
Specifies an HTTP header in the + request.
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, specifies to use the + PUT request method.
 - For PKI-authenticated Keystone - configurations, the token id value will be - much larger. + 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. - After you have obtained the token, you can use it to - make a requests to the Barbican API using the - integration environment. The following example shows - how to make a request for version information from - Barbican: - - If successful, the above command will return version - information for Barbican as shown in the following - example: - + 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. + + +
+ + Generating an authentication token + 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 tenant + in which your cloud runs. Ask your cloud administrator for + your user name, password, and tenant 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 Authenticate Request: JSON + + 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: + + + cURL Authenticate Response: JSON + + { +"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. + Using the Barbican API - In this chapter you will learn how to use the Barbican - API to create and retrieve secrets. - The first step in using the Barbican API is to create a - secret. In this section you will learn how to create your - first secret using the Barbican API. + 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 + + +
- Create a Secret - To generate a secret, you need to use the orders - resource, which is described in more detail in the - Barbican Developer Guide. You use the orders resource - to generate an order, which will then generate a - secret. - To generate an order, complete the following - steps: + Creating an order to store a secret + 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 as shown in the following - example: + a POST request at a + command-line interface, as shown in the + following example: - + + Uploading an Order JSON Request + Example + + + + If the call is successful, you will + receive a response like the following + one: + + {"order_ref": + "https://endpointURL/v1/tenantID/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc"} - You will receive a response like the - following. Make sure to note the order-ref - id that is returned in the URL. You will - use this id for the next request. - - {"order_ref": - "http://localhost:9311/v1/12345/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 at a command-line - interface: + following command: - curl -H 'Accept: text/plain' <'order_ref' obtained from the previous call> + curl -H 'Accept: text/plain' <http://endpointURL/v1/tenantID/orders/orderID - - - The call will return a response like the - following, Make sure to note the - secret-ref id that is returned in the - URL. + If the call is successful, it will + return a response like the following + one: - Retrieve the metadata for the generated - secret by typing the following at a - command-line interface: - - curl -H 'Accept: text/plain' <secret_ref id from the previous call> - - - - This call will return a response like - the following: - - + Record the secret ID that is returned in + the response (in this example, + 6c3ccd7d-46b6-4ece-9a58-a1be26b2758a).
-
- Retrieve a Secret - After you have generated a secret, you need to - verify that you can retrieve and view the - secret. - To view the secret in the format of random bytes, - type the following at a command line-interface: +
+ Retrieve order status + 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/octet-stream' <secret_ref id from the previous call> + curl -H 'Accept: application/json' https://endpointURL/v1/tenantID/orders/orderID - You will receive an intelligible response like the - following: - �l6[F���#��r�|gd�fe~��� + The following example shows an order with an ACTIVE + status: + { + "status": "ACTIVE", + "secret_ref": "endpointURL/v1/tenantID/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/tenantID/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/tenantID/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/tenantID/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0" + }
+
+ Storing a secret + 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/tenantID/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 a binary file to the + Barbican database directly for encrypted + storage. For more information, read Two-step call flow for binary secrets. + + +
+
+ Retrieving a secret + After you have created and 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 possilities + 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' https://endpointURL/v1/tenantID/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. + +
+
+ Retrieving a list of stored secrets + You can retrieve a list of secrets that are + associated with a given tenant by typing the following + command: + + curl -H 'Accept: application/json' https://endpointURL/v1/tenantID/secrets + + If the call is successful, you receive a response + like the following + one:{ + "secrets": [ + { + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/tenantID/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/tenantID/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/tenantID/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/tenantID/secrets?limit=10&offset=10" +} + +
+
+ Retrieving a list of orders + You can use a single GET request + to retrieve metadata for multiple orders for a given + tenant. To do so, type the following command: + + curl -H 'Accept: application/json' https://endpointURL/v1/tenantID/orders + + If the call is successful, you receive a response + like the following + one:{ + "total": 15, + "orders": [ + { + "status": "PENDING", + "secret_ref": "https://endpointURL/v1/tenantID/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/tenantID/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0" + }, + { + "status": "PENDING", + "secret_ref": "https://endpointURL/v1/tenantID/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/tenantID/orders/50212509-9c87-4a71-be3e-9ad59c290ede" + }, + { + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/tenantID/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/tenantID/orders/488cd596-f1a6-4abe-8cb0-16608f5b0359" + } + ], + "next": "https://endpointURL/v1/tenantID/orders?limit=10&offset=10" +} + +
+
Creating a secret using two-step storageYou 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' -d '{"name": "Binary Key File"}' http://endpointURL/v1/12345/secrets + + If the call is successfull, you receive + a 200 OK 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/12345/secrets/a83018d1-e657-4957-9ddd-42a479753e6b +x-openstack-request-id: req-ea090bd4-5bfc-47ae-a388-746485d947f1 + +{ + "secret_ref": "http://endpointURL/v1/12345/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’ \ + -T ./secret_key_file http://endpointURL/v1/12345/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. +
- Next Steps - To learn more details about the Barbican API, please - read the Barbican API Developer Guide. + Next steps + To learn more details about the Barbican API, read the + Barbican API Developer Guide. diff --git a/docs/src/docbkx/images/Barbican architecture drawing.png b/docs/src/docbkx/images/Barbican architecture drawing.png new file mode 100755 index 000000000..f41536961 Binary files /dev/null and b/docs/src/docbkx/images/Barbican architecture drawing.png differ diff --git a/docs/src/docbkx/samples/reqAuthenticate.json b/docs/src/docbkx/samples/reqAuthenticate.json index f84a7d202..32c6a4b75 100644 --- a/docs/src/docbkx/samples/reqAuthenticate.json +++ b/docs/src/docbkx/samples/reqAuthenticate.json @@ -1,17 +1,8 @@ -POST /v2.0/tokens HTTP/1.1 -User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6 -Host: identity.api.rackspacecloud.com -Accept: application/json -Content-Type: application/json -Content-Length: 54 - -{ - "auth": - { - "RAX-KSKEY:apiKeyCredentials": - { - "username": "jsmith", - "apiKey": "aaaaabbbbbccccc12345678" - } - } -} \ No newline at end of file +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 \ No newline at end of file diff --git a/docs/src/docbkx/samples/reqCreateOrder.json b/docs/src/docbkx/samples/reqCreateOrder.json index cb3a67ea0..ee6f022df 100644 --- a/docs/src/docbkx/samples/reqCreateOrder.json +++ b/docs/src/docbkx/samples/reqCreateOrder.json @@ -1,12 +1,13 @@ -curl -X POST -d \ +curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d \ '{ "secret": - { - "name": "secretname", - "algorithm": "aes", - "bit_length": 256, - "mode": "cbc", - "payload_content_type": "application/octet-stream" - } + { + "mode": "cbc", + "bit_length": 256, + "name": "secretname", + "algorithm": "aes", + "payload_content_type": "application/octet-stream" + } + } }'\ -http://localhost:9311/v1/12345/orders \ No newline at end of file +https://endpointURL/v1/tenantID/orders \ No newline at end of file diff --git a/docs/src/docbkx/samples/reqCreateSecret.json b/docs/src/docbkx/samples/reqCreateSecret.json index 462ea59c8..36977a689 100644 --- a/docs/src/docbkx/samples/reqCreateSecret.json +++ b/docs/src/docbkx/samples/reqCreateSecret.json @@ -1,6 +1,12 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d\ + '{ + "name": "AES key", + "expiration": "2014-02-28T19:14:44.180394", + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc", + "payload": "gF6+lLoF3ohA9aPRpt+6bQ==", + "payload_content_type": "application/octet-stream", + "payload_content_encoding": "base64" + }'\ + https://endpointURL/v1/tenantID/secrets \ No newline at end of file diff --git a/docs/src/docbkx/samples/reqCreateSecretwithoutPayload.json b/docs/src/docbkx/samples/reqCreateSecretwithoutPayload.json new file mode 100644 index 000000000..142943f9e --- /dev/null +++ b/docs/src/docbkx/samples/reqCreateSecretwithoutPayload.json @@ -0,0 +1,7 @@ +{ + "name": "AES key", + "expiration": "2014-02-28T19:14:44.180394", + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc" +} diff --git a/docs/src/docbkx/samples/reqUpdateSecret.json b/docs/src/docbkx/samples/reqUpdateSecret.json new file mode 100644 index 000000000..64f0bff07 --- /dev/null +++ b/docs/src/docbkx/samples/reqUpdateSecret.json @@ -0,0 +1,7 @@ +curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -d\ + '{ + "payload": "this is my secret", + "payload_content_type": "application/octet-stream", + "payload_content_encoding": "base64" + }'\ + https://endpointURL/v1/tenantID/secrets/secretID \ No newline at end of file diff --git a/docs/src/docbkx/samples/reqgetversioninfo.json b/docs/src/docbkx/samples/reqgetversioninfo.json index 1c5cfd7ce..07b678ac0 100644 --- a/docs/src/docbkx/samples/reqgetversioninfo.json +++ b/docs/src/docbkx/samples/reqgetversioninfo.json @@ -1,2 +1,2 @@ $ curl -H "Accept: application/json" -H "X-Auth-Token: 39a8b7f62dcb4095a74a4e65a68c85d8" \ - http://iad-int-api.cloudkeep.io:9311 + http://:9311 diff --git a/docs/src/docbkx/samples/resAuthenticate.json b/docs/src/docbkx/samples/resAuthenticate.json index 0aaa308c5..8c0b8ae67 100644 --- a/docs/src/docbkx/samples/resAuthenticate.json +++ b/docs/src/docbkx/samples/resAuthenticate.json @@ -7,141 +7,14 @@ Date: Thu, 8 Aug 2013 18:45:13 GMT "access": { "token": { - "expires": "2013-08-09T22:51:02.000-06:00", - "id": "vvvvvvvv-wwww-xxxx-yyyy-zzzzzzzzzzzz" - }, - "user": { - "id": "123456", - "name": "jsmith", - "RAX-AUTH:defaultRegion": "DFW", - "roles": [ - { - "description": "Admin Role.", - "id": "identity:admin", - "name": "identity:admin" - }, - { - "description": "Default Role.", - "id": "identity:default", - "name": "identity:default" - } - ] - }, - "serviceCatalog": [ - { - "endpoints": [ - { - "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/1100111", - "region": "DFW", - "tenantId": "1100111" - }, - { - "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/1100111", - "region": "ORD", - "tenantId": "1100111" + "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" } - ], - "name": "cloudDatabases", - "type": "rax:database" - }, - { - "endpoints": [ - { - "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/1100111", - "region": "DFW", - "tenantId": "1100111" - }, - { - "publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1100111", - "region": "ORD", - "tenantId": "1100111" - } - ], - "name": "cloudLoadBalancers", - "type": "rax:load-balancer" - }, - { - "endpoints": [ - { - "tenantId": "1100111", - "region": "DFW", - "publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/1100111", - "versionId": "2", - "versionInfo": "https://dfw.servers.api.rackspacecloud.com/v2/", - "versionList": "https://dfw.servers.api.rackspacecloud.com/" - }, - { - "tenantId": "1100111", - "region": "ORD", - "publicURL": "https://ord.servers.api.rackspacecloud.com/v2/1100111", - "versionId": "2", - "versionInfo": "https://ord.servers.api.rackspacecloud.com/v2/", - "versionList": "https://ord.servers.api.rackspacecloud.com/" - } - ], - "name": "cloudServersOpenStack", - "type": "compute" - }, - { - "endpoints": [ - { - "publicURL": "https://monitoring.api.rackspacecloud.com/v1.0/1100111", - "tenantId": "1100111" - } - ], - "name": "cloudMonitoring", - "type": "rax:monitor" - }, - { - "endpoints": [ - { - "publicURL": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/1100111", - "region": "DFW", - "tenantId": "1100111", - "versionId": "1.0", - "versionInfo": null, - "versionList": null - }, - { - "publicURL": "https://ord.autoscale.api.rackspacecloud.com/v1.0/1100111", - "region": "ORD", - "tenantId": "1100111", - "versionId": "1.0", - "versionInfo": null, - "versionList": null - } - ], - "name": "autoscale", - "type": "rax:autoscale" - }, - { - "endpoints": [ - { - "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "publicURL": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "region": "DFW" - }, - { - "tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "publicURL": "https://storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "internalURL": "https://snet-storage101.ord1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee", - "region": "ORD" - } - ], - "name": "cloudFiles", - "type": "object-store" - }, - { - "endpoints": [ - { - "tenantId": "1100111", - "publicURL": "https://dns.api.rackspacecloud.com/v1.0/1100111" - } - ], - "name": "cloudDNS", - "type": "rax:dns" - } - ] - } -} \ No newline at end of file + }, + } \ No newline at end of file diff --git a/docs/src/docbkx/samples/resCreateSecret.json b/docs/src/docbkx/samples/resCreateSecret.json index 463731fa6..af88228d9 100644 --- a/docs/src/docbkx/samples/resCreateSecret.json +++ b/docs/src/docbkx/samples/resCreateSecret.json @@ -1,13 +1,15 @@ { - "status": "ACTIVE", - "secret_ref": "http://localhost:9311/v1/12345/secrets/2df8d196-76b6-4f89-a6d2-c9e764900791", - "updated": "2013-11-04T16:39:13.608659", - "created": "2013-11-04T16:39:13.574489", - "secret": {"name": "secretname", - "algorithm": "aes", - "payload_content_type": "application/octet-stream", - "expiration": null, - "bit_length": 256, - "mode": "cbc" -}, - "order_ref": "http://localhost:9311/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc"} \ No newline at end of file + "status": "ACTIVE", + "secret_ref": "http://endpointURL/v1/123456/secrets/6c3ccd7d-46b6-4ece-9a58-a1be26b2758a", + "updated": "2014-04-28T15:14:39.025761", + "created": "2014-04-28T15:14:38.947844", + "secret": { + "name": "secretname", + "algorithm": "aes", + "payload_content_type": "application/octet-stream", + "expiration": null, + "bit_length": 256, + "mode": "cbc" + }, + "order_ref": "https://endpointURL/v1/123456/orders/4a20549c-b418-4548-b2d1-33016d88822d" +} \ No newline at end of file diff --git a/docs/src/docbkx/samples/resRetrieveSecret.json b/docs/src/docbkx/samples/resRetrieveSecret.json index 8fe588e19..f7fcb2e7e 100644 --- a/docs/src/docbkx/samples/resRetrieveSecret.json +++ b/docs/src/docbkx/samples/resRetrieveSecret.json @@ -1,12 +1,12 @@ { - "status": "ACTIVE", - "secret_ref": "http://localhost:9311/v1/12345/secrets/2df8d196-76b6-4f89-a6d2-c9e764900791", - "updated": "2013-11-04T16:39:13.593962", - "name": "secretname", - "algorithm": "aes", - "created": "2013-11-04T16:39:13.593956", - "content_types": {"default": "application/octet-stream"}, - "mode": "cbc", - "bit_length": 256, - "expiration": null + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/tenantID/secrets/2df8d196-76b6-4f89-a6d2-c9e764900791", + "updated": "2013-11-04T16:39:13.593962", + "name": "secretname", + "algorithm": "aes", + "created": "2013-11-04T16:39:13.593956", + "content_types": {"default": "application/octet-stream"}, + "mode": "cbc", + "bit_length": 256, + "expiration": null } diff --git a/docs/src/wadl/Barbican.wadl b/docs/src/wadl/Barbican.wadl index be55c3d34..e80d39a8e 100644 --- a/docs/src/wadl/Barbican.wadl +++ b/docs/src/wadl/Barbican.wadl @@ -1,94 +1,75 @@ - - %common; ]> - - - - - - - - - + xmlns:wadl="http://wadl.dev.java.net/2009/02" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0" + xmlns:raxapi="http://docs.rackspace.com/volume/api/v1" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:dbaas="http://docs.openstack.org/database/api/v1.0" + xmlns:db="http://docbook.org/ns/docbook"> + + + - - - - - - A subscriber to the Barbican service + + This parameter specifies the tenant ID of the client + subscribing to the Barbican service - - - - - - - - - - - - - - - A secret - - - + + + + + + + + + This parameter specifies the unique identifier of a secret that has been stored. + + + + + + + + + + + + + Specifies the unique identifier of an order that has been created. + + + + - - - - - - - - - - - - - An order - - - - - - - - - - - - - - - + + + + + + + - - This method retrieves all secrets. - This method lists all the secrets for a tenant. Calling this method does not provide information for an indiviual secret. + + This method retrieves all secrets for a given tenant. + This method lists all the secrets for a tenant. @@ -97,265 +78,268 @@ - - This status code is returned when the secrets have been successfully retrieved for the tenant. - + + This status code is returned when the + secrets have been successfully retrieved for the + tenant. + - - - - - - - - This method creates a secret. - This method creates a new secret. - Note: Making a POST request creates metadata for a secret. If the payload is provided with the POST request, it is encrypted and stored, and then linked with this metadata. If no payload is provided in the POST request, you need to make a subsequent PUT request and provide the payload. Clients must provide the secret information either via the PUT or POST request. Please note that this process differs from creating a secret by using the orders resource, whereby Barbican generates the actual secret information. - - - - - Specifies the human readable name for the secret. - This parameter is optional. If no name is - supplied, the UUID will be displayed for this - parameter on subsequent GET calls. - - - - Specifies the expiration date for the secret in - ISO-8601 format. ISO-8601 formats dates by using - the following representation: + + + + + + This method stores a secret. + This method stores a secret. + Note: The POST request creates and stores secret metadata. If the payload is provided with the POST request, it is encrypted and stored, and then linked with this metadata. If no payload is provided in the POST request, it must be provided in a subsequent PUT request. Using the secrets resource to store a secret differs from creating a secret by using the orders resource. When you make a POST requests using the orders resource, Barbican generates the actual secret information. + + + + + + + + Specifies the human readable name + for the secret. This parameter is optional. If no + name is supplied, the UUID will be displayed for + this parameter on subsequent GET calls. + + + + Specifies the expiration date for + the secret in ISO-8601 format. ISO-8601 formats + dates by using the following representation: yyyy-mm-ddThh:mm:ss[.mmm]. For example, September 27, 2012 is represented as 2012-09-27. Once the - secret has expired, it will no longer be returned - by the API or agent. This parameter is optinal. If - this parameter is not supplied, the secret has no - expiration date. - - - - Specifies the algorithm type used to generate the secret. This parameter is optional. - - - - - Specifies the bit length of the secret. Must be a positive integer. This parameter is optional. - - - - - Specifies the type/mode of the algorithm associated with the secret information. This parameter is optional. - - - - - Specifies the secret's unencrypted plain text. If - provided, this parameter's value must be - non-empty, and you must also provide the - payload_content_type. This field can be omitted - allowing for the secret information to be provided - via a subsequent PUT request. If the payload is - not provided, only the secret metadata will be + secret has expired, it is no longer returned + by the API or agent. This parameter is optional. + If this parameter is not supplied, the secret has + no expiration date. + + + Specifies the algorithm type used + to generate the secret. This parameter is + optional. Barbican does not validate the information provided for this parameter because it is client/application specific. + + + Specifies the bit length of the + secret. Must be a positive integer. This parameter + is optional. Barbican does not validate the information provided for this parameter because it is client/application specific. + + + Specifies the type/mode of the + algorithm associated with the secret information. + This parameter is optional. Barbican does not validate the information provided for this parameter because it is client/application specific. + + + Specifies the secret's unencrypted + plain text. If this parameter is specified, the + payload_content_type parameter must be specified + as well. If this parameter is not specified, you + can provide the payload information via a + subsequent PUT request. If the payload is not + provided, only the secret metadata will be retrievable from Barbican and any attempt to retrieve decrypted data for that secret will fail. Defering the secret information to a PUT request is useful for secrets that are in binary format - and are not suitable for base64 encoding. - - - + and are not suitable for base64 encoding. + + + + Specifies the type/format the secret data is provided in. This parameter is required if the payload parameter is specified. The following values are supported: - "text/plain" - This value is used to store plain text secrets. Other options are "text/plain; charset=utf-8". - If the charset value is omitted, utf-8 will be assumed. Note + If the charset value is omitted, UTF-8 will be assumed. Note that Barbican normalizes some formats before storing them as secret metadata, for example "text/plain; charset=utf-8" is converted to "text/plain." Retrieved metadata may not exactly match what was originally specified in the POST or PUT request. - When the payload_content_type parameter is set to "text/plain" you cannot specify a value for the payload_content_encoding parameter.. + When the payload_content_type parameter is set to "text/plain" you cannot specify a value for the payload_content_encoding parameter. - "application/octet-stream" - This value is used to store binary secrets from a base64 encoded payload. If this - value is used, you must also include the payload_content_encoding parameter. - - - - Specifies the encoding format used to provide the - payload data. Barbican might translate and store - the secret data into another format. This - parameter is required if the payload_content_type - parameter is set to "application/octet-stream." - The only possible value for this parameter is - "base64," which specifies base64 encoded payloads. - - - - - - - - - - This status code is returned when the secret has been successfully created. - - - - - - - - This error code is returned if the secret has invalid data. This response may include schema violations - such as mime-type not specified. + value is used, you must also include the payload_content_encoding parameter. + + + + Specifies the encoding format used + to provide the payload data. Barbican may + translate and store the secret data into another + format. This parameter is required if the + payload_content_type parameter is set to + "application/octet-stream." The only supported + value for this parameter is "base64," which + specifies base64-encoded payloads. + + + + + This status code is returned when the + secret has been successfully created. + + + + + - This error code is returned if the "payload" parameter is empty. This response indicates that the 'payload' JSON attribute was provided, but no value was assigned to it. + This error code is returned if the + secret has invalid data. This response may include + schema violations such as mime-type not specified. + - This error code is returned if the value specified in the "payload_content_type" parameter is not supported. It is caused when no crypto plugin supports the payload_content_type requested + This error code is returned if the + "payload" parameter is empty. This response indicates + that the 'payload' JSON attribute was provided, but no + value was assigned to it. + + + This error code is returned if the + value specified in the "payload_content_type" + parameter is not supported. It is caused when no + crypto plugin supports the payload_content_type + requested - This error code is returned when the secret specified in the "payload" parameter is too large. + This error code is returned when the + secret specified in the "payload" parameter is too + large. - - - - + + + - + This method retrieves secret information. - This method retrieves the information for the specified secret. For the application/json accept type, only metadata about the secret is returned. If one of the 'content_types' accept types is specified instead, that portion of the secret will be decrypted and returned. + This method retrieves the information for the specified secret. For the application/json accept type, only metadata about the secret is returned. If one of the 'content_types' accept types is specified instead, that portion of the secret will be decrypted and returned. - + - - This status code is returned when the secret has been successfully retrieved. - + + This status code is returned when the + secret has been successfully retrieved. + - This error code is returned when the supplied UUID doesn't match the secret in the datastore. + This error code is returned when the + supplied UUID doesn't match the secret in the + datastore. - This error code is returned when the secret metadata has been created, but the encrypted data for it has not yet been supplied, hence cannot be retrieved via a non 'application/json' mime type + This error code is returned when the + secret metadata has been created, but the encrypted + data for it has not yet been supplied, hence cannot be + retrieved via a non 'application/json' mime type - This error code is returned when the secret data cannot be retrieved in the requested Accept header mime-type + This error code is returned when the + secret data cannot be retrieved in the requested + Accept header mime-type - - - - - + + + - + This method updates a specified secret. - This method updates a secret. To provide secret information after the secret is created, submit a PUT request to the secret URI. Note that a PUT request can only be performed once after a POST call that does not include a payload. Also note that no other attributes of a secret can be modified via PUT after it is POST-ed. - The PUT request should include the payload, as well as the appropriate Content-Type and Content-Encoding definitions. - GET - Decrypted Secret Data - - To retrieve the decrypted secret information, perform a GET with the Accept header set to one of the content_types specified in the GET metadata call. Note that even if a binary secret is provided in the base64 format, it is converted to binary by Barbican prior to encryption and storage. Thereafter the secret will only be decrypted and returned as raw binary. + This method updates a secret. To provide secret information after the secret is created, submit a PUT request to the URI that contains the secret ID of the secret you want to update. Note that you can only make PUT request once after a POST call that does not include a payload. Also note that no other attributes of a secret can be modified via PUT.. + The PUT request should include the payload, as well as the appropriate Content-Type and Content-Encoding definitions. - - - Specifies the name of the last queue received in a previous request, or none to get the first page of results. - - - - - Specifies the number of queues to return. The default value for the number of queues returned is 10. If you do not specify this parameter, the default number of queues is returned. - - - - - Determines whether queue metadata is included in the response. The default value for this parameter is false, which excludes the metadata. - - - + - - This status code is returned when the secret has been successfully updated. - + + This status code is returned when the + secret has been successfully updated. + - This error code is returned when the supplied UUID doesn't match the secret in the datastore for the specified tenant.. + This error code is returned when the + supplied UUID doesn't match the secret in the + datastore for the specified tenant. - This error code is returned when no crypto plugin supports the payload_content_type requested in the Content-Type + This error code is returned when no + crypto plugin supports the payload_content_type + requested in the Content-Type header. - This error code is returned when the secret already has encrypted data associated with it + This error code is returned when the + secret already has encrypted data associated with + it. - This error code is returned when no value was provided for the "payload" parameter. + This error code is returned when no + value was provided for the "payload" parameter. - This error code is returned when the secret specified in the "payload" parameter is too large. - + This error code is returned when the + secret specified in the "payload" parameter is too + large. The current size limit is 10,000 bytes. + - - - - - - - Deletes the specified secret. - This operation immediately deletes a queue and all of its existing messages. - - - - - - - - - - This status code is returned when the secret has been successfully deleted. - - - - - - - - This error code is returned when the supplied UUID doesn't match the secret in the datastore. - - - - - - - - - - - + + + + + + + + - - This method retrieves all orders. + + This method retrieves all orders for a given tenant. This method lists all orders for a specified tenant. Performing a GET on the secrets resource with no UUID retrieves a batch of the most recent orders per the requesting tenant. The retrieved list of orders is ordered by oldest to newest created date. @@ -366,180 +350,165 @@ The following values are supported: - - This status code is returned when the orders have been successfully retrieved. - + + This status code is returned when the + orders have been successfully retrieved. + - - - - - - - - This method creates an order. - This method creates a new order. - - - - - This parameter specifies the name of the secret. - - - - - Specifies the algorithm type used to generate the secret. This parameter is optional. - - - - - Specifies the bit length of the secret. Must be a positive integer. This parameter is optional. - - - - - Specifies the type/mode of the algorithm associated with the secret information. This parameter is optional. - - - - - Specifies the type/format the secret data is provided in. This parameter is required if the payload parameter is specified. - The following values are supported: - - "text/plain" - This value is used to store plain text secrets. - Other options are "text/plain; charset=utf-8". - If the charset value is omitted, utf-8 will be assumed. Note - that Barbican normalizes some formats before storing them - as secret metadata, for example - "text/plain; charset=utf-8" is converted to "text/plain." Retrieved metadata may not exactly match what was originally - specified in the POST or PUT request. - When the payload_content_type parameter is set to "text/plain" you cannot specify a value for the payload_content_encoding parameter.. - - "application/octet-stream" - This value is used to store binary - secrets from a base64 encoded payload. If this - value is used, you must also include the payload_content_encoding parameter. - - - - - - - - - This status code is returned when the order was successfully created. - - - - - - - - This error code is returned when the data provided in the POST request is invalid. This can include schema violations such as the secret's mime-type not specified - - - This error code is returned when the value provided in the "payload_content_type" parameter is invalid. This is caused when thre is no crypto plugin available that supports the payload_content_type requested - - - - - - - - - - - This method retrieves information about a specified order. - This method retrieves information for the specified order including g a link to the secret that was generated as a result of the order (if available). - - - - - - - - - - This status code is returned when the order info was successfully retrieved. - - - - - - - - This error code is returned when the supplied UUID doesn't match a order in the data store, which means the order doesn't exist. - - - - - - + + + + + This method creates an order. + This method creates a new order. + + + + + + + + This parameter specifies the name + of the secret. + + + + Specifies the algorithm type used to store the + secret. This parameter is optional. + + + Specifies the bit length of the + secret. Must be a positive integer. This parameter + is optional. + + + Specifies the type/mode of the + algorithm associated with the secret information. + This parameter is optional. + + + + Specifies the type/format the secret data is provided in. + + + + + + This status code is returned when the + order was successfully created. + + + + + + + + This error code is returned when the + data provided in the POST request is invalid. This can + include schema violations such as the secret's + mime-type not specified + + + This error code is returned when the + value provided in the "payload_content_type" parameter + is invalid. This is caused when thre is no crypto + plugin available that supports the + payload_content_type requested + + + + + + + + This method retrieves information about a specified order. + This method retrieves information for the specified order including g a link to the secret that was stored as a result of the order (if available). + + + + + + + + + + This status code is returned when the + order info was successfully retrieved. + + + + + + + + This error code is returned when the + supplied UUID doesn't match a order in the data store, + which means the order doesn't exist. + + + + + - - This method updates an order. - - - - - Specifies the name of the last queue received in a previous request, or none to get the first page of results. - - - - - Specifies the number of queues to return. The default value for the number of queues returned is 10. If you do not specify this parameter, the default number of queues is returned. - - - - - Determines whether queue metadata is included in the response. The default value for this parameter is false, which excludes the metadata. - - - - - - - - - - - - - - - - - - - - - - - This method deletes the specified order. - This method cancels an exisitng order. - - - - - - - - - - This status code is returned when the order was successfully cancelled. - - - - - - - - This error code is returned when the supplied UUID doesn't match a order in the data store, which means the order doesn't exist. - - - - + + This method updates an order. + + + + Specifies the name of the last + queue received in a previous request, or none to + get the first page of results. + + + Specifies the number of queues to + return. The default value for the number of queues + returned is 10. If you do not specify this + parameter, the default number of queues is + returned. + + + Determines whether queue metadata + is included in the response. The default value for + this parameter is false, which + excludes the metadata. + + + + + + + + + + + + + + + + diff --git a/docs/src/wadl/samples/db-auth.json b/docs/src/wadl/samples/db-auth.json deleted file mode 100644 index 583b584c0..000000000 --- a/docs/src/wadl/samples/db-auth.json +++ /dev/null @@ -1,72 +0,0 @@ -HTTP/1.1 200 OK -Content-Type: application/json; charset=UTF-8 -Content-Length: 477 -Date: Thu, 12 Apr 2012 18:45:13 GMT - -{ - "auth": { - "serviceCatalog": { - "cloudDNS": [ - { - "publicURL": "https://dns.api.rackspacecloud.com/v1.0/1234" - } - ], - "cloudDatabases": [ - { - "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/1234", - "region": "DFW" - }, - { - "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/1234", - "region": "ORD" - } - ], - "cloudFiles": [ - { - "internalURL": "https://snet-storage101.dfw1.clouddrive.com/v1/ MossoCloudFS_aaaa-bbbbb-cccc-ddddd ", - "publicURL": "https://storage101.dfw1.clouddrive.com/v1/ MossoCloudFS_aaaa-bbbbb-cccc-ddddd ", - "region": "DFW", - "v1Default": true - } - ], - "cloudFilesCDN": [ - { - "publicURL": "https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaa-bbbbb-cccc-ddddd", - "region": "DFW", - "v1Default": true - } - ], - "cloudLoadBalancers": [ - { - "publicURL": "https://ord.loadbalancers.api.rackspacecloud.com/v1.0/1234", - "region": "ORD" - }, - { - "publicURL": "https://dfw.loadbalancers.api.rackspacecloud.com/v1.0/1234", - "region": "DFW" - } - ], - "cloudMonitoring": [ - { - "publicURL": "https://monitoring.api.rackspacecloud.com/v1.0/1234" - } - ], - "cloudServers": [ - { - "publicURL": "https://servers.api.rackspacecloud.com/v1.0/1234", - "v1Default": true - } - ], - "cloudServersOpenStack": [ - { - "publicURL": "https://dfw.servers.api.rackspacecloud.com/v2/1234", - "region": "DFW" - } - ] - }, - "token": { - "expires": "2012-04-12T13:15:52.000-05:00", - "id": "aaaaa-bbbbbb-cccccc-ddddd" - } - } -} diff --git a/docs/src/wadl/samples/db-auth.xml b/docs/src/wadl/samples/db-auth.xml deleted file mode 100644 index 35bb35e28..000000000 --- a/docs/src/wadl/samples/db-auth.xml +++ /dev/null @@ -1,50 +0,0 @@ -HTTP/1.1 200 OK -Content-Type: application/xml; charset=UTF-8 -Content-Length: 477 -Date: Thu, 12 Apr 2012 18:50:20 GMT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/src/wadl/samples/db-credentials.json b/docs/src/wadl/samples/db-credentials.json deleted file mode 100644 index bf15936f9..000000000 --- a/docs/src/wadl/samples/db-credentials.json +++ /dev/null @@ -1,13 +0,0 @@ -POST /v1.1/auth HTTP/1.1 -User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6 -Host: auth.api.rackspacecloud.com -Accept: application/json -Content-Type: application/json -Content-Length: 54 - -{ - "credentials" : { - "username" : "hub_cap", - "key" : "a86850deb2742ec3cb41518e26aa2d89" - } -} diff --git a/docs/src/wadl/samples/db-credentials.xml b/docs/src/wadl/samples/db-credentials.xml deleted file mode 100644 index ae7f8971e..000000000 --- a/docs/src/wadl/samples/db-credentials.xml +++ /dev/null @@ -1,11 +0,0 @@ -POST /v1.1/auth HTTP/1.1 -User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.15 libssh2/1.2.6 -Host: auth.api.rackspacecloud.com -Accept: application/xml -Content-Type: application/xml -Content-Length: 88 - - - diff --git a/docs/src/wadl/samples/db-faults-badRequest.json b/docs/src/wadl/samples/db-faults-badRequest.json deleted file mode 100644 index fcb4571af..000000000 --- a/docs/src/wadl/samples/db-faults-badRequest.json +++ /dev/null @@ -1,11 +0,0 @@ -HTTP/1.1 400 None -Content-Length: 120 -Content-Type: application/json; charset=UTF-8 -Date: Tue, 29 Nov 2011 00:33:48 GMT - -{ - "badRequest": { - "code": 400, - "message": "Volume 'size' needs to be a positive integer value, -1.0 cannot be accepted." - } -} diff --git a/docs/src/wadl/samples/db-faults-badRequest.xml b/docs/src/wadl/samples/db-faults-badRequest.xml deleted file mode 100644 index 43a6c7fe8..000000000 --- a/docs/src/wadl/samples/db-faults-badRequest.xml +++ /dev/null @@ -1,10 +0,0 @@ -HTTP/1.1 400 None -Content-Type: application/xml -Content-Length: 121 -Date: Mon, 28 Nov 2011 18:19:37 GMT - - - - Volume 'size' needs to be a positive integer value, -1.0 cannot be accepted. - - diff --git a/docs/src/wadl/samples/db-faults-instanceFault.json b/docs/src/wadl/samples/db-faults-instanceFault.json deleted file mode 100644 index c1235773a..000000000 --- a/docs/src/wadl/samples/db-faults-instanceFault.json +++ /dev/null @@ -1,11 +0,0 @@ -HTTP/1.1 500 Internal Server Error -Content-Length: 120 -Content-Type: application/json; charset=UTF-8 -Date: Tue, 29 Nov 2011 00:33:48 GMT - -{ - "instance_fault": { - "code": 500, - "message": "The server has either erred or is incapable of performing the requested operation." - } -} diff --git a/docs/src/wadl/samples/db-faults-instanceFault.xml b/docs/src/wadl/samples/db-faults-instanceFault.xml deleted file mode 100644 index 40a1ecfb4..000000000 --- a/docs/src/wadl/samples/db-faults-instanceFault.xml +++ /dev/null @@ -1,10 +0,0 @@ -HTTP/1.1 500 Internal Server Error -Content-Type: application/xml -Content-Length: 121 -Date: Mon, 28 Nov 2011 18:19:37 GMT - - - - The server has either erred or is incapable of performing the requested operation. - - diff --git a/docs/src/wadl/samples/db-faults-itemNotFound.json b/docs/src/wadl/samples/db-faults-itemNotFound.json deleted file mode 100644 index df2edda30..000000000 --- a/docs/src/wadl/samples/db-faults-itemNotFound.json +++ /dev/null @@ -1,11 +0,0 @@ -HTTP/1.1 404 Not Found -Content-Length: 78 -Content-Type: application/json; charset=UTF-8 -Date: Tue, 29 Nov 2011 00:35:24 GMT - -{ - "item_not_found": { - "code": 404, - "message": "The resource could not be found." - } -} diff --git a/docs/src/wadl/samples/db-faults-itemNotFound.xml b/docs/src/wadl/samples/db-faults-itemNotFound.xml deleted file mode 100644 index 7a09fc608..000000000 --- a/docs/src/wadl/samples/db-faults-itemNotFound.xml +++ /dev/null @@ -1,10 +0,0 @@ -HTTP/1.1 404 Not Found -Content-Length: 147 -Content-Type: application/xml; charset=UTF-8 -Date: Mon, 28 Nov 2011 19:50:15 GMT - - - - The resource could not be found. - - diff --git a/docs/src/wadl/samples/db-request-types.json b/docs/src/wadl/samples/db-request-types.json deleted file mode 100644 index 7d7283da0..000000000 --- a/docs/src/wadl/samples/db-request-types.json +++ /dev/null @@ -1,15 +0,0 @@ -POST /v1.0/1234/instances HTTP/1.1 -Host: ord.databases.api.rackspacecloud.com -Content-Type: application/json -Accept: application/xml -X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - -{ - "instance": { - "name": "'my_instance_name'", - "flavor_ref": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1", - "volume": { - "size": "2" - } - } -} \ No newline at end of file diff --git a/docs/src/wadl/samples/db-response-types.xml b/docs/src/wadl/samples/db-response-types.xml deleted file mode 100644 index 186b77924..000000000 --- a/docs/src/wadl/samples/db-response-types.xml +++ /dev/null @@ -1,24 +0,0 @@ -HTTP/1.1 200 OK -Content-Type: application/xml -Content-Length: 380 -Date: Thu, 17 Nov 2011 02:37:37 GMT - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/src/wadl/samples/reqCreateOrder.json b/docs/src/wadl/samples/reqCreateOrder.json index ef859a94c..8d9b681ec 100644 --- a/docs/src/wadl/samples/reqCreateOrder.json +++ b/docs/src/wadl/samples/reqCreateOrder.json @@ -9,4 +9,5 @@ curl -X POST -d \ "payload_content_type": "application/octet-stream" } }'\ -http://localhost:9311/v1/12345/orders \ No newline at end of file +https://endpointURL/v1/12345/orders + diff --git a/docs/src/wadl/samples/reqCreateSecret.json b/docs/src/wadl/samples/reqCreateSecret.json index 462ea59c8..168b683c6 100644 --- a/docs/src/wadl/samples/reqCreateSecret.json +++ b/docs/src/wadl/samples/reqCreateSecret.json @@ -1,6 +1,12 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d\ + '{ + "name": "AES key", + "expiration": "2014-02-28T19:14:44.180394", + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc", + "payload": "gF6+lLoF3ohA9aPRpt+6bQ==", + "payload_content_type": "application/octet-stream", + "payload_content_encoding": "base64" + }' + https://endpointURL/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqDeleteOrder.json b/docs/src/wadl/samples/reqDeleteOrder.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/reqDeleteOrder.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqDeleteSecret.json b/docs/src/wadl/samples/reqDeleteSecret.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/reqDeleteSecret.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqGetOrderinfo copy.json b/docs/src/wadl/samples/reqGetOrderinfo copy.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/reqGetOrderinfo copy.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqGetOrderinfo.json b/docs/src/wadl/samples/reqGetOrderinfo.json index 159822152..88353e9cc 100644 --- a/docs/src/wadl/samples/reqGetOrderinfo.json +++ b/docs/src/wadl/samples/reqGetOrderinfo.json @@ -1 +1,2 @@ -curl http://localhost:9311/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc \ No newline at end of file +curl -H 'Accept: application/json'\ +https://endpointURL/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc \ No newline at end of file diff --git a/docs/src/wadl/samples/reqGetOrders.json b/docs/src/wadl/samples/reqGetOrders.json index 462ea59c8..7052e62dc 100644 --- a/docs/src/wadl/samples/reqGetOrders.json +++ b/docs/src/wadl/samples/reqGetOrders.json @@ -1,6 +1,2 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +curl -H 'Accept: application/json'\ +https://endpointURL/v1/12345/orders \ No newline at end of file diff --git a/docs/src/wadl/samples/reqGetSecretinfo.json b/docs/src/wadl/samples/reqGetSecretinfo.json index a88abbf5b..ae1e01dbb 100644 --- a/docs/src/wadl/samples/reqGetSecretinfo.json +++ b/docs/src/wadl/samples/reqGetSecretinfo.json @@ -1 +1,2 @@ -GET v1/{tenant_id}/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718 \ No newline at end of file +curl -H 'Accept: application/json' \ +https://endpointURL/v1/12345/secrets/secretID/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718 \ No newline at end of file diff --git a/docs/src/wadl/samples/reqGetSecrets.json b/docs/src/wadl/samples/reqGetSecrets.json index 462ea59c8..121ffb558 100644 --- a/docs/src/wadl/samples/reqGetSecrets.json +++ b/docs/src/wadl/samples/reqGetSecrets.json @@ -1,6 +1,2 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +curl -H 'Accept: application/json'\ +https://endpointURL/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqUpdateOrder.json b/docs/src/wadl/samples/reqUpdateOrder.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/reqUpdateOrder.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/reqUpdateSecret.json b/docs/src/wadl/samples/reqUpdateSecret.json index 462ea59c8..40991f8a0 100644 --- a/docs/src/wadl/samples/reqUpdateSecret.json +++ b/docs/src/wadl/samples/reqUpdateSecret.json @@ -1,6 +1,2 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +curl -i -X PUT -H 'Content-Type: application/octet-stream’ \ + -T ./secret_key_file http://endpointURL/v1/12345/secrets/a83018d1-e657-4957-9ddd-42a479753e6b \ No newline at end of file diff --git a/docs/src/wadl/samples/resCreateOrder.json b/docs/src/wadl/samples/resCreateOrder.json index fefcf5282..19c81448f 100644 --- a/docs/src/wadl/samples/resCreateOrder.json +++ b/docs/src/wadl/samples/resCreateOrder.json @@ -1,3 +1,3 @@ { - "order_ref": "http://localhost:9311/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc" + "order_ref": "http://endpointURL/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc" } \ No newline at end of file diff --git a/docs/src/wadl/samples/resCreateSecret.json b/docs/src/wadl/samples/resCreateSecret.json index 547c814ec..12e461210 100644 --- a/docs/src/wadl/samples/resCreateSecret.json +++ b/docs/src/wadl/samples/resCreateSecret.json @@ -1,3 +1,3 @@ { - "secret_ref": "http://localhost:9311/v1/{tenant_id}/secrets/a8957047-16c6-4b05-ac57-8621edd0e9ee" + "secret_ref": "https://endpointURL/v1/12345/secrets/513ed616-2686-4ce5-a96c-fea785fe527b" } \ No newline at end of file diff --git a/docs/src/wadl/samples/resDeleteOrder.json b/docs/src/wadl/samples/resDeleteOrder.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/resDeleteOrder.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/resDeleteSecret.json b/docs/src/wadl/samples/resDeleteSecret.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/resDeleteSecret.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/resGetOrderinfo.json b/docs/src/wadl/samples/resGetOrderinfo.json index 159822152..d7f9c0786 100644 --- a/docs/src/wadl/samples/resGetOrderinfo.json +++ b/docs/src/wadl/samples/resGetOrderinfo.json @@ -1 +1,14 @@ -curl http://localhost:9311/v1/12345/orders/62d57f53-ecfe-4ae4-87bd-fab2f24e29bc \ No newline at end of file +{ + "status": "ACTIVE", + "secret_ref": "endpointURL/v1/12345/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/12345/orders/b63d2c05-5d53-4db6-af06-4e388044deb8" \ No newline at end of file diff --git a/docs/src/wadl/samples/resGetOrders.json b/docs/src/wadl/samples/resGetOrders.json index 462ea59c8..f99253750 100644 --- a/docs/src/wadl/samples/resGetOrders.json +++ b/docs/src/wadl/samples/resGetOrders.json @@ -1,6 +1,50 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +{ + "total": 15, + "orders": [ + { + "status": "PENDING", + "secret_ref": "https://endpointURL/v1/12345/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/12345/orders/94ade532-9657-41e1-87ae-c8cbdfa836e0" + }, + { + "status": "PENDING", + "secret_ref": "https://endpointURL/v1/12345/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/12345/orders/50212509-9c87-4a71-be3e-9ad59c290ede" + }, + { + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/12345/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/12345/orders/488cd596-f1a6-4abe-8cb0-16608f5b0359" + } + ], + "next": "https://endpointURL/v1/12345/orders?limit=10&offset=10" \ No newline at end of file diff --git a/docs/src/wadl/samples/resUpdateOrder.json b/docs/src/wadl/samples/resUpdateOrder.json deleted file mode 100644 index 462ea59c8..000000000 --- a/docs/src/wadl/samples/resUpdateOrder.json +++ /dev/null @@ -1,6 +0,0 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file diff --git a/docs/src/wadl/samples/resUpdateSecret.json b/docs/src/wadl/samples/resUpdateSecret.json index 462ea59c8..6fd4f92f3 100644 --- a/docs/src/wadl/samples/resUpdateSecret.json +++ b/docs/src/wadl/samples/resUpdateSecret.json @@ -1,6 +1,3 @@ -curl -X POST -d \ -'{ - "payload": "my-secret-here", - "payload_content_type": "text/plain" - }'\ - http://localhost:9311/v1/12345/secrets \ No newline at end of file +HTTP/1.1 200 OK +Content-Length: 0 +x-openstack-request-id: req-ab107dce-adfd-4b8d-b9eb-7095f8cf9b15 \ No newline at end of file diff --git a/docs/src/wadl/samples/resgetSecretinfo.json b/docs/src/wadl/samples/resgetSecretinfo.json index 66239c2c3..40d8debe0 100644 --- a/docs/src/wadl/samples/resgetSecretinfo.json +++ b/docs/src/wadl/samples/resgetSecretinfo.json @@ -1,13 +1,14 @@ { - "status": "ACTIVE", - "updated": "2013-06-28T15:23:33.092660", - "name": "AES key", - "algorithm": "AES", - "mode": "cbc", - "bit_length": 256, - "content_types": { - "default": "application/octet-stream" - }, - "expiration": "2013-05-08T16:21:38.134160", - "secret_ref": "http://localhost:8080/v1/12345/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718", + "status": "ACTIVE", + "secret_ref": "https://endpointURL/v1/12345/secrets/513ed616-2686-4ce5-a96c-fea785fe527b", + "updated": "2014-05-02T06:29:25.415271", + "name": "AES key", + "algorithm": "aes", + "created": "2014-05-02T06:29:25.415261", + "content_types": { + "default": "application/octet-stream" + }, + "mode": "cbc", + "bit_length": 256, + "expiration": "2014-05-28T19:14:44.180394" } \ No newline at end of file diff --git a/docs/src/wadl/samples/resgetSecrets.json b/docs/src/wadl/samples/resgetSecrets.json index a4d0bda4b..910a65c5f 100644 --- a/docs/src/wadl/samples/resgetSecrets.json +++ b/docs/src/wadl/samples/resgetSecrets.json @@ -7,7 +7,7 @@ "name": "Main Encryption Key", "algorithm": "AES", "created": "2013-06-28T15:23:30.668619", - "secret_ref": "http://localhost:9311/v1/12345/secrets/e171bb2d-f14f-433e-84f0-3dfcac7a7311", + "secret_ref": "http://endpointURL/v1/12345/secrets/e171bb2d-f14f-433e-84f0-3dfcac7a7311", "expiration": "2014-06-28T15:23:30.668619", "bit_length": 256, "content_types": { @@ -21,7 +21,7 @@ "name": "Backup Key", "algorithm": "AES", "created": "2013-06-28T15:23:32.210467", - "secret_ref": "http://localhost:9311/v1/12345/secrets/6dba7827-c232-4a2b-8f3d-f523ca3a3f99", + "secret_ref": "http://endpointURL/v1/12345/secrets/6dba7827-c232-4a2b-8f3d-f523ca3a3f99", "expiration": null, "bit_length": 256, "content_types": { @@ -35,7 +35,7 @@ "name": "PostgreSQL admin password", "algorithm": null, "created": "2013-06-28T15:23:33.092635", - "secret_ref": "http://localhost:9311/v1/12345/secrets/6dfa448d-c35a-4158-abaf-e4c249efb580", + "secret_ref": "http://endpointURL/v1/12345/secrets/6dfa448d-c35a-4158-abaf-e4c249efb580", "expiration": null, "bit_length": null, "content_types": { @@ -43,6 +43,6 @@ } } ], - "next": "http://localhost:9311/v1/12345/secrets?limit=3&offset=5", - "previous": "http://localhost:9311/v1/12345/secrets?limit=3&offset=0" + "next": "http://endpointURL/v1/12345/secrets?limit=3&offset=5", + "previous": "http://endpointURL/v1/12345/secrets?limit=3&offset=0" } \ No newline at end of file diff --git a/docs/src/wadl/samples/resgetversioninfo.json b/docs/src/wadl/samples/resgetversioninfo.json deleted file mode 100644 index 7b6c1505b..000000000 --- a/docs/src/wadl/samples/resgetversioninfo.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "v1": "current", - "build": "2013.2.20130913025647" -} diff --git a/docs/src/wadl/samples/snapshot_create.json b/docs/src/wadl/samples/snapshot_create.json deleted file mode 100644 index 48fc7b560..000000000 --- a/docs/src/wadl/samples/snapshot_create.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "snapshot": { - "display_name": "snap-001", - "display_description": "Daily backup", - "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c", - "force": true - } -} diff --git a/docs/src/wadl/samples/snapshot_create.xml b/docs/src/wadl/samples/snapshot_create.xml deleted file mode 100644 index 3d6d95aa1..000000000 --- a/docs/src/wadl/samples/snapshot_create.xml +++ /dev/null @@ -1,7 +0,0 @@ - - diff --git a/docs/src/wadl/samples/snapshot_list_simple.json b/docs/src/wadl/samples/snapshot_list_simple.json deleted file mode 100644 index 7e216f3c7..000000000 --- a/docs/src/wadl/samples/snapshot_list_simple.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "snapshots": [ - { - "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5", - "display_name": "snap-001", - "display_description": "Daily backup", - "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c", - "status": "available", - "size": 100, - "createdAt": "2012-02-29T03:50:07Z" - }, - { - "id": "e479997c-650b-40a4-9dfe-77655818b0d2", - "display_name": "snap-002", - "display_description": "Weekly backup", - "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358", - "status": "available", - "size": 100, - "createdAt": "2012-03-19T01:52:47Z" - } - ] -} diff --git a/docs/src/wadl/samples/snapshot_list_simple.xml b/docs/src/wadl/samples/snapshot_list_simple.xml deleted file mode 100644 index 9eb4c754d..000000000 --- a/docs/src/wadl/samples/snapshot_list_simple.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - - - diff --git a/docs/src/wadl/samples/snapshot_show.json b/docs/src/wadl/samples/snapshot_show.json deleted file mode 100644 index 9ef042a50..000000000 --- a/docs/src/wadl/samples/snapshot_show.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "snapshot": { - "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5", - "display_name": "snap-001", - "display_description": "Daily backup", - "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c", - "status": "creating", - "size": 100, - "createdAt": "2012-02-29T03:50:07Z" - } -} diff --git a/docs/src/wadl/samples/snapshot_show.xml b/docs/src/wadl/samples/snapshot_show.xml deleted file mode 100644 index 8b78bf502..000000000 --- a/docs/src/wadl/samples/snapshot_show.xml +++ /dev/null @@ -1,9 +0,0 @@ - - diff --git a/docs/src/wadl/samples/volume_create.json b/docs/src/wadl/samples/volume_create.json deleted file mode 100644 index 6189d29b6..000000000 --- a/docs/src/wadl/samples/volume_create.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "volume": { - "display_name": "vol-001", - "display_description": "Another volume.", - "size": 100, - "volume_type": "SATA", - } -} diff --git a/docs/src/wadl/samples/volume_create.xml b/docs/src/wadl/samples/volume_create.xml deleted file mode 100644 index 5f9522a54..000000000 --- a/docs/src/wadl/samples/volume_create.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - diff --git a/docs/src/wadl/samples/volume_list_simple.json b/docs/src/wadl/samples/volume_list_simple.json deleted file mode 100644 index 2ed92e367..000000000 --- a/docs/src/wadl/samples/volume_list_simple.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "volumes": [ - { - "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c", - "display_name": "vol-001", - "display_description": "Another volume.", - "size": 100, - "volume_type": "1", - "snapshot_id": null, - "attachments": [], - "createdAt": "2012-02-14T20:53:07Z" - }, - { - "id": "76b8950a-8594-4e5b-8dce-0dfa9c696358", - "display_name": "vol-002", - "display_description": "Yet another volume.", - "size": 100, - "volume_type": "1", - "snapshot_id": null, - "attachments": [], - "createdAt": "2012-03-15T19:10:03Z" - } - ] -} diff --git a/docs/src/wadl/samples/volume_list_simple.xml b/docs/src/wadl/samples/volume_list_simple.xml deleted file mode 100644 index 9b4b01cf5..000000000 --- a/docs/src/wadl/samples/volume_list_simple.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - diff --git a/docs/src/wadl/samples/volume_show.json b/docs/src/wadl/samples/volume_show.json deleted file mode 100644 index d24fdbd14..000000000 --- a/docs/src/wadl/samples/volume_show.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "volume": { - "id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c", - "display_name": "vol-001", - "display_description": "Another volume.", - "size": 100, - "volume_type": "1", - "snapshot_id": null, - "attachments": [], - "createdAt": "2012-02-14T20:53:07Z" - } -} diff --git a/docs/src/wadl/samples/volume_show.xml b/docs/src/wadl/samples/volume_show.xml deleted file mode 100644 index 40abfae97..000000000 --- a/docs/src/wadl/samples/volume_show.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - diff --git a/docs/src/wadl/samples/volume_type_list.json b/docs/src/wadl/samples/volume_type_list.json deleted file mode 100644 index 596fb5d1c..000000000 --- a/docs/src/wadl/samples/volume_type_list.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "volume_types": [ - { - "id": 1, - "name": "SATA", - "extra_specs": {}, - }, - { - "id": 2, - "name": "SSD", - "extra_specs": {}, - } - ] -} - diff --git a/docs/src/wadl/samples/volume_type_list.xml b/docs/src/wadl/samples/volume_type_list.xml deleted file mode 100644 index bb5b1d495..000000000 --- a/docs/src/wadl/samples/volume_type_list.xml +++ /dev/null @@ -1,9 +0,0 @@ - -> - - - - - - - diff --git a/docs/src/wadl/samples/volume_type_show.json b/docs/src/wadl/samples/volume_type_show.json deleted file mode 100644 index fbff156e1..000000000 --- a/docs/src/wadl/samples/volume_type_show.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "volume_type": { - "id": "1", - "name": "SATA", - "extra_specs": {}, - } -} \ No newline at end of file diff --git a/docs/src/wadl/samples/volume_type_show.xml b/docs/src/wadl/samples/volume_type_show.xml deleted file mode 100644 index 3fd35f725..000000000 --- a/docs/src/wadl/samples/volume_type_show.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - - - -