This wiki page details the API for the latest Barbican release. In particular:
The barbican service is assumed to be hosted on an SSL enabled, geographically labelled endpoint. An example for a valid URI might look like the following:
Versioning will be achieved through a URI constant element, as shown in the example below:
Resource access in Barbican is subject to RBAC constraints, as detailed in this link. RBAC failures will result in a 403 Forbidden response.
Secrets Resource Moved to Secrets Reference
The ordering 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.
An example of an orders POST request is below.
POST v1/orders
Header: content-type=application/json
X-Project-Id: {project_id}
{
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "AES",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
}
}
Where the elements of the meta element match those of the secret POST request above, but without the payload attributes. _Note however that unlike with the secrets resource, the algorithm, bit_length and mode attributes are validated, to ensure that a secret can be generated per these specifications._ The type parameter selects the secret to generate: key generates a symmetric key; asymmetric generates a public/private PKI key pair (in a Container object); certificate` generates an SSL certificate (not currently operational).
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.
Currently nothing can be edited in an order.
GET requests for an order will return a response such as in the example below.
GET v1/orders/{order_id}
Headers: X-Project-Id: {project_id}
{
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:8080/v1/orders/f9b633d8-fda5-4be8-b42c-5b2c9280289e",
"secret_ref": "http://localhost:8080/v1/secrets/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718",
"status": "ERROR",
"error_status_code": "400 Bad Request",
"error_reason": "Secret creation issue seen - content-encoding of 'bogus' not supported."
}
Where:
Performing a GET on the orders resource with no UUID retrieves a batch of the most recent orders per the requesting project, as per the example response below. The limit and offset parameters function similar to the GET secrets list detailed above.
GET http://localhost:9311/v1/orders?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"orders": [
{
"status": "ACTIVE",
"secret_ref": "http://localhost:9311/v1/secrets/bf2b33d5-5347-4afb-9009-b4597f415b7f",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/orders/3100078a-6ab1-4c3f-ab9f-295938c91733"
},
{
"status": "ACTIVE",
"secret_ref": "http://localhost:9311/v1/secrets/fa71b143-f10e-4f7a-aa82-cc292dc33eb5",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/orders/30b3758a-7b8e-4f2c-b9f0-f590c6f8cc6d"
}
]
}
The retrieved list of orders is ordered by oldest to newest created date.
| Method | Description |
|---|---|
| GET | Returns a list of all orders for a customer. |
| POST | Starts the process of creating a secret. This call will return immediately with a 202 OK and a link to the detail order object (see below). |
> https://.../v1/orders/{order_uuid}
| Method | Description |
|---|---|
| GET | Returns the detailed order data including a link to the secret generated as a result of the order (if available). |
| PUT | Not yet supported. Allows the editing of an order where allowed. |
| DELETE | Cancels an order. |
| Action | Error Code | Notes |
|---|---|---|
| POST order with invalid data | 400 | Can include schema violations such as the secret’s mime-type not specified |
| POST order with ‘Content-Type’ header not supported | 415 | Caused when the API doesn’t support the specified Content-Type header |
| POST secret with ‘payload_content_type’ not supported | 400 | Caused when no crypto plugin supports the payload_content_type requested |
| GET order that doesn’t exist | 404 | The supplied UUID doesn’t match a order in the data store |
| DELETE order that doesn’t exist | 404 | The supplied UUID doesn’t match a order in the data store |
Containers Resource Moved to Containers Reference
The consumers resource allows clients to register as interested in specific container instances (as created per the previous section). Clients can then query containers for the consumers that registered interest in them. Client workflows could use this list (for example) to warn of attempts to remove containers that have registered consumers. Note that Barbican allows containers to be deleted even if there are registered consumers for them.
An example of an consumers POST request is below.
POST v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers
Header: content-type=application/json
X-Project-Id: {project_id}
{
"name": "foo-service",
"URL": "https://www.fooservice.com/widgets/1234"
}
Where the name is typically the name of the remote service registering as a consumer for this container instance, and ‘URL’ is typically a URL to a resource in the remote service that utilizes the container’s secrets somehow, such as a load balancer that has a container’s SSL certificate installed onto it.
Note that subsequent POSTs to the same container instance with the same name attribute will replace the previous URL registered for that name.
Note: This feature seems to be broken currently, by not displaying the navigation links per the example below.
Performing a GET on a specific container resource returns a list of consumers that registered with it. The limit and offset parameters function similar to the GET secrets list detailed above.
GET http://localhost:9311/v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers?limit=3&offset=2
Headers: X-Project-Id: {project_id}
{
"consumers": [
{
"name": "foo-service",
"URL": "https://www.fooservice.com/widgets/1234"
},
{
"name": "barService",
"URL": "https://www.barservice.com/mythings/5678"
}
],
"next":"http://localhost:9311/v1/containers/888b29a4-c7cf-49d0-bfdf-bd9e6f26d718/consumers?limit=10&offset=10"
}
The retrieved list of consumers is ordered by oldest to newest created date.
> https://.../v1/containers/<container-UUID>/consumers
| Method | Description |
|---|---|
| GET | Returns a list of all consumers registered for a container. |
| POST | Registers/adds consumer information to a container. |
| DELETE | Removes a registered consumer by specifying its name and URL in the JSON payload. |
The following are example combinations, inspired by this page.
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.
| Action | content-type | content-encoding | Result |
|---|---|---|---|
| POST secrets | payload_content_type = text/plain | payload_content_encoding Not required/ignored | Supplied payload is encrypted |
| GET secrets (meta) | Accept: application/json | Not required/ignored | JSON metadata, with Content-Types set to ‘default’:’text/plain’ |
| GET secrets | Accept: text/plain | Not required/ignored | Previous payload is decrypted and returned |
| Action | content-type | content-encoding | Result |
|---|---|---|---|
| POST secrets | payload_content_type = application/octet-stream | payload_content_encoding = base64 | Supplied payload is converted from base64 to binary, then encrypted. |
| GET secrets (meta) | Accept: application/json | Not required/ignored | JSON metadata, with Content-Types set to ‘default’:’application/octet-stream’ |
| GET secrets (decrypted) | Accept: application/octet-stream | Not specified | Previous payload is decrypted and returned as raw binary, even if the POST provided the data in `base64`. |
| Action | content-type | content-encoding | Result |
|---|---|---|---|
| POST secrets |
|
payload_content_encoding Not required/ignored | Only 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 |
| PUT secrets (option #1 - as base64) | Content-Type: application/octet-stream | Content-Encoding: base64 | Supplied request body is converted from base64 to binary, then encrypted |
| PUT secrets (option #2 - as binary) | Content-Type: application/octet-stream | Not specified | Supplied request body is encrypted as is |
| GET secrets (meta) | Accept: application/json | Not required/ignored | JSON metadata, with Content-Types set to ‘default’:’application/octet-stream’ |
| GET secrets (decrypted) | Accept: application/octet-stream | Not specified | Previous request is decrypted and returned as raw binary, even if the PUT provided the data in `base64`. |
| Action | content-type | content-encoding | Result |
|---|---|---|---|
| POST secrets | payload_content_type Not required/ignored | payload_content_encoding Not required/ignored | Only 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 secrets | Content-Type: text/plain | Not required/ignored | Supplied request body is encrypted as is |
| GET secrets (meta) | Accept: application/json | Not required/ignored | JSON metadata, with Content-Types set to ‘default’:’text/plain’ |
| GET secrets (decrypted) | Accept: text/plain | Not specified | Previous request is decrypted and returned as utf-8 text |