openstack/barbican
Code Issues Proposed changes

Adding docs to index and minor fixes

Browse Source 
Removed reference to secrets and containers from
original api documentation as well as removed
reference to original api doc page. Orders and
consumers have not been verified and therefore
have not been ported over.

Change-Id: I590a6d4b76ae3ce06bf042df9aa004338af866ec
This commit is contained in:
Chellygel 2015-04-01 09:54:11 -05:00
parent ace2daaa3a
commit 0d504d3ba3
4 changed files with 10 additions and 652 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

656
doc/source/api.rst
View File

@ -2,6 +2,10 @@
Application Programming Interface
=================================
THESE DOCS ARE DEPRECATED AS OF APR 2015
########################################
This wiki page details the API for the latest Barbican release. In particular:
* `Endpoints & Versioning`_ - Brief discussion about Barbican's approach to
@ -41,390 +45,7 @@ RBAC failures will result in a 403 Forbidden response.
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 several formats, but additional
functionality may be available for known types of symmetric or asymmetric keys.
The schema for storing a secret differs from the retrieval schema is shown
next.
Storing Secrets
---------------
Secrets can be stored in two ways: Via POST including a payload ('one step'
secret storage), or with a POST without a payload followed by a PUT ('two step'
secret storage).
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, a follow-on PUT call provides this payload. Hence clients
must provide the secret information payload to store via these operations. This
should not be confused with the secret 'generation' process via the `orders`
resource below, whereby Barbican generates the secret information payload on
clients' behalf.
POST
~~~~
Below is an example of a `secret` POST request that includes a payload.
.. code-block:: javascript
POST v1/secrets
Header: content-type=application/json
X-Project-Id: {project_id}
{
"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",
"secret_type": "opaque"
}
Where:
* **name** - (optional) Human readable name for the secret. If a name is not
supplied, the UUID will be displayed for this field on subsequent GET calls
(see below).
* **expiration** - (optional) The 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. If this field is not supplied, then the secret has no
expiration date.
* **algorithm** - (optional) The algorithm type used to generate the secret.
_Barbican does not attempt to validate the information provided here, as it
is client/application specific._
* **bit_length** - (optional) The bit-length of the secret. Must be an integer
one or greater. *Barbican does not attempt to validate the information
provided here, as it is client/application specific.*
* **mode** - (optional) The type/mode of the algorithm associated with the
secret information. _Barbican does not attempt to validate the information
provided here, as it is client/application specific._
* **payload** - (optional) The secret's unencrypted plain text. If provided,
this field'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 call (see below)._
* **payload_content_type** - (optional) The type/format the secret data is
provided in. Required if `payload` is specified. Supported values are:
* _"text/plain"_ - Used to store plain text secrets.
* Other options are _"text/plain; charset=utf-8"_. If charset is
omitted, utf-8 will be assumed.
* Note that some types are normalized before being stored as secret
meta-data, such as converting "text/plain; charset=utf-8" to
"text/plain". *Hence retrieved meta-data may not exactly match what
was specified in the POST or PUT calls*.
* payload_content_encoding must **not** be specified when
payload_content_type is _"text/plain"_
* _"application/octet-stream"_ - Used to store binary secrets from a base64
encoded payload. If this value is used, you must also include the
content encoding.
* **payload_content_encoding** - (optional) The _encoding_ format used to
provide the payload data. Barbican might translate and store the secret data
into another format. _Required if `payload_content_type` is
"application/octet-stream"._ Supported values are:
* _"base64"_ - Used to specify base64 encoded payloads.
* **secret_type** - (optional) Used to indicate the type of secret being
stored. If no value is given, `opaque` is used as the default, which is used
to signal Barbican to just store the information without worrying about
format or encoding. Options for this value are `symmetric`, `public`,
`private`, `passphrase`, `certificate`, `opaque`.
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. Deferring the secret information to a PUT request is useful for secrets
that are in binary format and are not suitable for base64 encoding.
If the Content-Type in the HTTP header is not set to "application/json" then
the POST call will fail with an HTTP 415 error.
If the POST call succeeds, a URI to the new secret will be provided such as per
the example below:
.. code-block:: javascript
{
"secret_ref": "http://localhost:9311/v1/secrets/a8957047-16c6-4b05-ac57-8621edd0e9ee"
}
PUT
~~~
To provide secret information after the secret's metadata is add, clients would
send 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 (i.e. secrets are immutable).
The PUT request must include the appropriate Content-Type and Content-Encoding
definitions. (see Examples below for more information.)
Retrieving Secrets
------------------
Secrets are comprised of metadata about the secret (algorithm, bit-length,
etc.) and encrypted payload data associated with the secret. Hence the API
supports retrieving either a secret's metadata or its decrypted data.
GET - Individual Secret - Metadata Only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
GET requests for a `secret` with an `Accept` header set to `application/json`
will return a response such as the one below. Only metadata about the secret is
returned, rather than the decrypted secret information itself. This allows for
a more rapid response for large secrets, or large lists of secrets, as well as
accommodating multi-part secrets such as SSL certificates, which may have both
a public and private key portions that could be individually retrieved.
An example GET call for an individual secret is below.
.. code-block:: javascript
GET v1/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718
Headers: X-Project-Id: {project_id}
{
"status": "ACTIVE",
"secret_type": "symmetric",
"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/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718",
}
Where:
* **secret_type** - See POST example above.
* **name** - Human readable name for the secret. If a name was not provided
during the POST call above, then its UUID is returned.
* **algorithm** - See POST example above.
* **mode** - See POST example above.
* **bit_length** - See POST example above.
* **content_types** - Available content mime types for the format of the
decrypted secret. For example, SSL certificates may have both 'public' (for
public key) and 'private' (for private key) types available.
* *This value is only shown if a secret has encrypted data associated with
it.*
* Note that some types are normalized, such as converting "text/plain;
charset=utf-8" to "text/plain". *Hence retrieved meta-data may not
exactly match what was specified in the POST or PUT calls*.
* **expiration** - UTC time when the secret will expire. Attempting to
retrieve a secret after the expiration date will result in an error.
* **secret_ref** - Self URI to the secret.
GET - List of Secrets Per Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Performing a GET on the secrets resource with no UUID retrieves a batch of the
most recent secrets (metadata only) per the requesting project, as per the
example response below. The `limit` and `offset` parameters are used to control
pagination of the secrets list, as described after this example.
.. code-block:: javascript
GET http://localhost:9311/v1/secrets?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"secrets": [
{
"status": "ACTIVE",
"secret_type": "symmetric",
"updated": "2013-06-28T15:23:30.668641",
"mode": "cbc",
"name": "Main Encryption Key",
"algorithm": "AES",
"created": "2013-06-28T15:23:30.668619",
"secret_ref": "http://localhost:9311/v1/secrets/e171bb2d-f14f-433e-84f0-3dfcac7a7311",
"expiration": "2014-06-28T15:23:30.668619",
"bit_length": 256,
"content_types": {
"default": "application/octet-stream"
}
},
{
"status": "ACTIVE",
"secret_type": "symmetric",
"updated": "2013-06-28T15:23:32.210474",
"mode": "cbc",
"name": "Backup Key",
"algorithm": "AES",
"created": "2013-06-28T15:23:32.210467",
"secret_ref": "http://localhost:9311/v1/secrets/6dba7827-c232-4a2b-8f3d-f523ca3a3f99",
"expiration": null,
"bit_length": 256,
"content_types": {
"default": "application/octet-stream"
}
},
{
"status": "ACTIVE",
"secret_type": "passphrase"
"updated": "2013-06-28T15:23:33.092660",
"mode": null,
"name": "PostgreSQL admin password",
"algorithm": null,
"created": "2013-06-28T15:23:33.092635",
"secret_ref": "http://localhost:9311/v1/secrets/6dfa448d-c35a-4158-abaf-e4c249efb580",
"expiration": null,
"bit_length": null,
"content_types": {
"default": "text/plain"
}
}
],
"next": "http://localhost:9311/v1/secrets?limit=3&offset=5",
"previous": "http://localhost:9311/v1/secrets?limit=3&offset=0"
}
The retrieved list of secrets is ordered by oldest to newest `created` date.
The URL parameters (`?limit=3&offset=2` in this example) provide a way to
window or page the retrieved list, with the `offset` representing how many
records to skip before retrieving the list, and the `limit` representing the
maximum number of records retrieved (up to `100`). If the parameters are not
provided, then up to `10` records are retrieved.
To access any records before the retrieved list, the 'previous' link is
provided. The 'next' link can be used to retrieve records after the current
list.
GET - Decrypted Secret Data
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To retrieve the decrypted secret information, one must append 'payload' to the
path of the desired secret, and 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._ See examples
below for more info.
Secrets Summary
---------------
> https://.../v1/secrets
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Allows a user to list all secrets in a project. _Note: the actual |
| | secret payload data will not be listed here. Clients must instead |
| | make a separate call to get the secret details to view the |
| | secret._ |
+--------+-------------------------------------------------------------------+
| POST | Allows a user to create a new secret. This call expects the user |
| | to provide a secret. To have the API generate a secret, see the |
| | `orders` API below. Returns 201 if the secret has been created. |
+--------+-------------------------------------------------------------------+
> https://.../v1/secrets/{secret_uuid}/
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Gets the information for the specified secret. For the |
| | `application/json` accept type, only metadata about the secret is |
| | returned. |
| | _The following is deprecated:_ If one of the 'content_types' |
| | accept types is specified, that portion of the secret will be |
| | be decrypted and returned. |
+--------+-------------------------------------------------------------------+
| PUT | Allows the user to upload secret data for a specified secret _(if |
| | the secret does not already have data associated with it)_. |
| | Returns 200 on a successful request. |
+--------+-------------------------------------------------------------------+
| DELETE | Deletes the secret. |
+--------+-------------------------------------------------------------------+
> https://.../v1/secrets/{secret_uuid}/payload/
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Will decrypt a secret using the specified accept type. The accept |
| | type must be one of the 'content_types' available from the secret |
| | metadata |
+--------+-------------------------------------------------------------------+
Error Responses
~~~~~~~~~~~~~~~
+------------------------+-------+-------------------------------------------+
| Action | Error | Notes |
| | Code | |
+========================+=======+===========================================+
| POST secret with | 400 | Can include schema violations such as |
| invalid data | | mime-type not specified. |
+------------------------+-------+-------------------------------------------+
| POST secret with | 400 | The 'payload' JSON attribute was |
| 'payload' empty | | provided, but no value was assigned to |
| | | it. |
+------------------------+-------+-------------------------------------------+
| POST secret with | 413 | Current size limit is 10,000 bytes |
| 'payload' too | | |
| large | | |
+------------------------+-------+-------------------------------------------+
| POST secret with | 400 | Caused when no crypto plugin supports the |
| 'payload_content_type' | | payload_content_type requested |
| not supported | | |
+------------------------+-------+-------------------------------------------+
| POST secret with | 415 | Caused when the API doesn't support the |
| 'Content-Type' header | | specified Content-Type header |
| not supported | | |
+------------------------+-------+-------------------------------------------+
| GET secret that | 404 | The supplied UUID doesn't match a secret |
| doesn't exist | | in the data store |
+------------------------+-------+-------------------------------------------+
| GET secret with | 406 | The secret data cannot be retrieved in |
| unsupported Accept | | the requested Accept header mime-type |
+------------------------+-------+-------------------------------------------+
| GET secret (non-JSON) | 404 | The secret metadata has been created, but |
| with no associated | | the encrypted data for it has not yet been|
| encrypted data | | supplied, hence cannot be retrieved via a |
| | | non 'application/json' mime type |
+------------------------+-------+-------------------------------------------+
| PUT secret that | 404 | The supplied UUID doesn't match a secret |
| doesn't exist | | in the data store for the given project |
+------------------------+-------+-------------------------------------------+
| PUT secret with | 415 | Caused when no crypto plugin supports the |
| unsupported | | payload_content_type requested in the |
| Content-Type | | Content-Type |
+------------------------+-------+-------------------------------------------+
| PUT secret that | 409 | Secret already has encrypted data |
| already has encrypted | | associated with it |
| data | | |
+------------------------+-------+-------------------------------------------+
| PUT secret with empty | 400 | No value was provided in the payload |
| 'payload' data | | |
+------------------------+-------+-------------------------------------------+
| PUT secret with too | 413 | Current size limit is 10,000 bytes for |
| large 'payload' data | | uploaded secret data |
+------------------------+-------+-------------------------------------------+
| DELETE secret that | 404 | The supplied UUID doesn't match a secret |
| doesn't exist | | in the data store |
+------------------------+-------+-------------------------------------------+
Secrets Resource Moved to :doc:`Secrets Reference <api/reference/secrets>`
Orders Resource
===============
@ -627,272 +248,7 @@ Error Responses
Containers Resource
===================
Containers store references to secrets. There are currently three types of
containers ("generic", "rsa", and "certificate").
Generic type containers can hold multiple references to secrets, each reference
defining a relation name to the secret. RSA type containers can hold 3 secret
references, named 'public_key', 'private_key', and 'private_key_passphrase'.
Certificate type containers must hold a 'certificate', but may optionally hold
any or all of 'private_key', 'private_key_passphrase', and 'intermediates'.
POST
----
Below is an example of a `container` POST request.
.. code-block:: javascript
POST v1/containers
Header: content-type=application/json
{
"name": "container name",
"type": "rsa",
"secret_refs": [
{
"name": "private_key",
"secret_ref":"http://localhost:9311/v1/secrets/05a47308-d045-43d6-bfe3-1dbcd0c3a97b"
},
{
"name": "public_key",
"secret_ref":"http://localhost:9311/v1/secrets/8b9ea25d-2324-4ef3-891f-2a821ad88ed1"
},
{
"name": "private_key_passphrase",
"secret_ref":"http://localhost:9311/v1/secrets/c39c04dd-e423-457e-8993-063d8a0a187c"
}
]
}
Where:
* **name** - (optional) Human readable name for the container. If a name is not
supplied, the UUID will be displayed for this field on subsequent GET calls
(see below).
* **type** - The type of the container. Type can be "generic", "rsa", or
"certificate". The "generic" type containers can store multiple arbitrary
named references to secrets; "rsa" type can store 3 references, one each
named "public_key", "private_key" and "private_key_passphrase"; "certificate"
type must hold a "certificate", but may optionally hold any or all of
"private_key", "private_key_passphrase", and "intermediates".
* **secret_refs** - (optional) Array of secret references.
If the POST call succeeds, a URI to the new container will be provided such as
per the example below:
.. code-block:: javascript
{
"container_ref": "http://localhost:9311/v1/containers/a8957047-16c6-4b05-ac57-8621edd0e9ee"
}
If the Content-Type in the HTTP header is not set to "application/json" then
the POST call will fail with an HTTP 415 error.
PUT
---
Currently nothing can be edited in a container resource.
GET - Individual Container
--------------------------
GET requests for a container will return a response such as in the example
below
.. code-block:: javascript
GET v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718
{
"name":"rsa container",
"secret_refs":[
{
"secret_ref":"http://localhost:9311/v1/secrets/059805d5-b400-47da-abc5-cae7286d3ede",
"name":"private_key_passphrase"
},
{
"secret_ref":"http://localhost:9311/v1/secrets/28704f0f-3273-40d4-bc40-4de2691135ea",
"name":"private_key"
},
{
"secret_ref":"http://localhost:9311/v1/secrets/29d89344-10ad-4f92-8aa2-adebaf7556ee",
"name":"public_key"
}
],
"container_ref":"http://localhost:9311/v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718",
"type":"rsa"
}
Where:
* **name** - Human readable name for the container. If a name was not provided
during the POST call above, then its UUID is returned.
* **type** - Type of the container.
* **container_ref** - Self URI to the container.
* **secret_refs** - Array of named secret references.
GET - List of Containers Per Project
------------------------------------
Performing a GET on the containers resource with no UUID retrieves a batch of
the most recent containers per the requesting project, as per the example
response below. The `limit` and `offset` parameters function similar to the GET
secrets list detailed above.
.. code-block:: javascript
GET http://localhost:9311/v1/containers?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"total":42,
"containers":[
{
"status":"ACTIVE",
"updated":"2014-02-11T18:05:58.909411",
"name":"generic container_updated",
"secret_refs":[
{
"secret_id":"123",
"name":"private_key"
},
{
"secret_id":"321",
"name":"public_key"
},
{
"secret_id":"456",
"name":"private_key_passphrase"
}
],
"created":"2014-02-11T18:05:58.909403",
"container_ref":"http://localhost:9311/v1/containers/d4e06015-4f6e-4626-ac3d-4ece6621f96d",
"type":"rsa"
},
{
"status":"ACTIVE",
"updated":"2014-02-11T18:08:58.160557",
"name":"generic container_updated",
"secret_refs":[
{
"secret_id":"321",
"name":"public_key"
},
{
"secret_id":"456",
"name":"private_key_passphrase"
}
],
"created":"2014-02-11T18:08:58.160551",
"container_ref":"http://localhost:9311/v1/containers/bb24fa61-0b5f-4d40-8990-846e95cd7b12",
"type":"rsa"
},
{
"status":"ACTIVE",
"updated":"2014-02-11T18:25:58.198072",
"name":"generic container_updated",
"secret_refs":[
{
"secret_id":"1df433d6-c2d4-480d-90fb-0bfd9c5da3dd",
"name":"private_key"
},
{
"secret_id":"321",
"name":"public_key"
},
{
"secret_id":"456",
"name":"private_key_passphrase"
}
],
"created":"2014-02-11T18:25:58.198063",
"container_ref":"http://localhost:9311/v1/containers/38f58696-5013-4bd6-ab2b-fbea41dc957a",
"type":"rsa"
},
{
"status":"ACTIVE",
"updated":"2014-02-11T18:44:06.296957",
"name":"generic container_updated",
"secret_refs":[
{
"secret_id":"1df433d6-c2d4-480d-90fb-0bfd9c5da3dd",
"name":"private_key"
},
{
"secret_id":"321",
"name":"public_key"
},
{
"secret_id":"456",
"name":"private_key_passphrase"
}
],
"created":"2014-02-11T18:44:06.296947",
"container_ref":"http://localhost:9311/v1/containers/a8d1adfd-0d36-4eb0-8762-99787eb4a7ff",
"type":"rsa"
}
],
"next":"http://localhost:9311/v1/containers?limit=10&offset=10"
}
The retrieved list of containers is ordered by oldest to newest `created` date.
The URL parameters (`?limit=3&offset=2` in this example) provide a way to
window or page the retrieved list, with the `offset` representing how many
records to skip before retrieving the list, and the `limit` representing the
maximum number of records retrieved (up to `100`). If the parameters are not
provided, then up to `10` records are retrieved.
To access any records before the retrieved list, the 'previous' link is
provided. The 'next' link can be used to retrieve records after the current
list.
Containers Summary
------------------
> https://.../v1/containers
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Allows a user to list all containers in a project._ |
+--------+-------------------------------------------------------------------+
| POST | Allows a user to create a new container. Returns 201 if the |
| | container has been created. |
+--------+-------------------------------------------------------------------+
> https://.../v1/containers/{container_uuid}/
+--------+-------------------------------------------------------------------+
| Method | Description |
+========+===================================================================+
| GET | Gets the information for the specified container. |
+--------+-------------------------------------------------------------------+
| PUT | Currently not supported. |
+--------+-------------------------------------------------------------------+
| DELETE | Deletes the container. |
+--------+-------------------------------------------------------------------+
Error Responses
~~~~~~~~~~~~~~~
+------------------------+-------+-------------------------------------------+
| Action | Error | Notes |
| | Code | |
+========================+=======+===========================================+
| POST container with | 400 | Can include schema violations such as |
| invalid data | | container type not specified |
+------------------------+-------+-------------------------------------------+
| GET container that | 404 | The supplied UUID doesn't match a |
| doesn't exist | | container in the data store |
+------------------------+-------+-------------------------------------------+
| DELETE container that | 404 | The supplied UUID doesn't match a secret |
| doesn't exist | | in the data store |
+------------------------+-------+-------------------------------------------+
Containers Resource Moved to :doc:`Containers Reference <api/reference/containers>`
Consumers Resource
==================

1
doc/source/api/index.rst
View File

@ -9,6 +9,7 @@ Quick Start
:maxdepth: 1
./quickstart/secrets
./quickstart/containers
API Reference

2
doc/source/api/quickstart/secrets.rst
View File

@ -8,7 +8,7 @@ to the secret / keying material stored in the system.
Barbican supports the storage of data for various content-types securely.
This guide will assume you will be using a local running development environment of Barbican.
If you need assistance with getting set up, please reference the :doc:`development guide <../setup/dev>`.
If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
What is a Secret?

3
doc/source/index.rst
View File

@ -16,7 +16,7 @@ Getting Started
.. toctree::
:maxdepth: 1
api
api/index
contribute/getting_involved
contribute/dependencies
contribute/database_migrations
@ -25,6 +25,7 @@ Getting Started
plugin/index
Indices and tables
==================