168 lines
6.0 KiB
ReStructuredText
168 lines
6.0 KiB
ReStructuredText
***********************
|
|
Orders API - User Guide
|
|
***********************
|
|
|
|
The orders resource allows the user to request barbican to generate a secret.
|
|
This is also very helpful for requesting the creation of public/private key pairs.
|
|
|
|
The orders resource supports the following types:
|
|
* symmetric keys
|
|
* asymmetric keys
|
|
|
|
This user guide provides high level examples of the orders resource.
|
|
It will assume you will be using a local running development environment of barbican.
|
|
If you need assistance with getting set up, please reference the
|
|
`development guide <https://docs.openstack.org/barbican/latest/contributor/dev.html>`__.
|
|
|
|
.. _create_order:
|
|
|
|
Creating an Order
|
|
#################
|
|
|
|
When you want barbican to generate a secret you need to create an order.
|
|
For an order to be processed correctly the parameters mode,
|
|
bit_length, and algorithm must be valid. Otherwise the order will fail and
|
|
the secret will not be generated. The example below shows a valid order for
|
|
generating a symmetric key. You can find a more detailed explanation about
|
|
the parameters in the
|
|
`Orders API <https://docs.openstack.org/barbican/latest/api/reference/orders.html>`__
|
|
documentation.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X POST -H "X-Auth-Token: $TOKEN" -H "content-type:application/json" -d '{
|
|
"type":"key", "meta": { "name": "secretname", "algorithm": "aes",
|
|
"bit_length": 256, "mode": "cbc", "payload_content_type": "application/octet-stream"}
|
|
}' http://localhost:9311/v1/orders
|
|
|
|
You should receive an order reference after placing your order with barbican.
|
|
|
|
.. code-block:: bash
|
|
|
|
{"order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942"}
|
|
|
|
The order reference is used to retrieve the metadata for the order you placed
|
|
which can then be used to retrieve your secret.
|
|
|
|
.. _retrieve_order:
|
|
|
|
Retrieving an Order
|
|
###################
|
|
|
|
In order to retrieve the order we will use the reference returned during
|
|
the initial creation. (See :ref:`Creating an Order <create_order>`.)
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' \
|
|
http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942
|
|
|
|
The typical response is below:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"created": "2015-10-15T18:15:10",
|
|
"creator_id": "40540f978fbd45c1af18910e3e02b63f",
|
|
"meta": {
|
|
"algorithm": "AES",
|
|
"bit_length": 256,
|
|
"expiration": null,
|
|
"mode": "cbc",
|
|
"name": "secretname",
|
|
"payload_content_type": "application/octet-stream"
|
|
},
|
|
"order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
|
|
"status": "ACTIVE",
|
|
"sub_status": "Unknown",
|
|
"sub_status_message": "Unknown",
|
|
"type": "key",
|
|
"updated": "2015-10-15T18:15:10"
|
|
}
|
|
|
|
This is the metadata associated with the order.
|
|
To retrieve the secret generated by the order, refer to the :doc:`Secrets User Guide <secrets>`.
|
|
The order metadata is very useful for determining if your order was processed
|
|
correctly. Since orders are processed asynchronously, you can use the metadata
|
|
returned for the order to verify a successful secret creation.
|
|
The parameters of the response are explained in more detail
|
|
`here <https://docs.openstack.org/barbican/latest/api/reference/orders.html#get-unique-order-response-attributes>`__.
|
|
|
|
.. _retrieve_order_list:
|
|
|
|
Retrieving All Orders
|
|
#####################
|
|
|
|
It is also possible to retrieve all orders for a project.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"orders": [
|
|
{
|
|
"created": "2015-10-15T18:15:10",
|
|
"creator_id": "40540f978fbd45c1af18910e3e02b63f",
|
|
"meta": {
|
|
"algorithm": "AES",
|
|
"bit_length": 256,
|
|
"expiration": null,
|
|
"mode": "cbc",
|
|
"name": "secretname",
|
|
"payload_content_type": "application/octet-stream"
|
|
},
|
|
"order_ref": "http://localhost:9311/v1/orders/3a5c6748-44de-4c1c-9e54-085c3f79e942",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/bcd1b853-edeb-4509-9f12-019b8c8dfb5f",
|
|
"status": "ACTIVE",
|
|
"sub_status": "Unknown",
|
|
"sub_status_message": "Unknown",
|
|
"type": "key",
|
|
"updated": "2015-10-15T18:15:10"
|
|
},
|
|
{
|
|
"created": "2015-10-15T18:51:35",
|
|
"creator_id": "40540f978fbd45c1af18910e3e02b63f",
|
|
"meta": {
|
|
"algorithm": "AES",
|
|
"bit_length": 256,
|
|
"mode": "cbc",
|
|
"expiration": null,
|
|
"name": null
|
|
},
|
|
"order_ref": "http://localhost:9311/v1/orders/d99ced51-ea7a-4c14-8e11-0dda0f49c5be",
|
|
"secret_ref": "http://localhost:9311/v1/secrets/abadd306-8235-4f6b-984a-cc48ad039def",
|
|
"status": "ACTIVE",
|
|
"sub_status": "Unknown",
|
|
"sub_status_message": "Unknown",
|
|
"type": "key",
|
|
"updated": "2015-10-15T18:51:35"
|
|
}
|
|
],
|
|
"total": 2
|
|
}
|
|
|
|
You can refer to the
|
|
`orders parameters <https://docs.openstack.org/barbican/latest/api/reference/orders.html#get-order-parameters>`__
|
|
section of the
|
|
`Orders API <https://docs.openstack.org/barbican/latest/api/reference/orders.html>`__
|
|
documentation in order to refine your search among orders.
|
|
|
|
.. _delete_order:
|
|
|
|
Deleting an Order
|
|
#################
|
|
|
|
It is also possible to delete an order from barbican.
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -X DELETE -H "X-Auth-Token: $TOKEN" -H 'Accept:application/json' http://localhost:9311/v1/orders/fbdd845f-4a5e-43e3-8f68-64e8f106c486
|
|
|
|
Nothing will be returned when you delete an order.
|
|
If something was returned there was most likely an error while deleting
|
|
the order.
|