401 lines
17 KiB
ReStructuredText
401 lines
17 KiB
ReStructuredText
***********************
|
|
Secrets API - Reference
|
|
***********************
|
|
|
|
GET /v1/secrets
|
|
###############
|
|
Lists a project's secrets.
|
|
|
|
The list of secrets can be filtered by the parameters passed in via the URL.
|
|
|
|
|
|
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.
|
|
|
|
.. _secret_parameters:
|
|
|
|
Parameters
|
|
**********
|
|
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+========+=========+================================================================+
|
|
| offset | integer | The starting index within the total list of the secrets that |
|
|
| | | you would like to retrieve. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| limit | integer | The maximum number of records to return (up to 100). The |
|
|
| | | default limit is 10. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| name | string | Selects all secrets with name equal to this value. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| bits | integer | Selects all secrets with bit_length equal to this value. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| alg | string | Selects all secrets with algorithm equal to this value. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
| mode | string | Selects all secrets with mode equal to this value. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
|
|
.. _secret_response_attributes:
|
|
|
|
Response Attributes
|
|
*******************
|
|
|
|
+----------+---------+--------------------------------------------------------------+
|
|
| Name | Type | Description |
|
|
+==========+=========+==============================================================+
|
|
| secrets | list | Contains a list of dictionaries filled with secret metadata. |
|
|
+----------+---------+--------------------------------------------------------------+
|
|
| total | integer | The total number of secrets available to the user. |
|
|
+----------+---------+--------------------------------------------------------------+
|
|
| next | string | A HATEOS url to retrieve the next set of secrets based on |
|
|
| | | the offset and limit parameters. This attribute is only |
|
|
| | | available when the total number of secrets is greater than |
|
|
| | | offset and limit parameter combined. |
|
|
+----------+---------+--------------------------------------------------------------+
|
|
| previous | string | A HATEOS url to retrieve the previous set of secrets based |
|
|
| | | on the offset and limit parameters. This attribute is only |
|
|
| | | available when the request offset is greater than 0. |
|
|
+----------+---------+--------------------------------------------------------------+
|
|
|
|
|
|
.. _secret_status_codes:
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 200 | Successful Request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
|
|
|
|
.. _post_secrets:
|
|
|
|
POST /v1/secrets
|
|
################
|
|
Creates a secret
|
|
|
|
Attributes
|
|
**********
|
|
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| Attribute Name | Type | Description | Default |
|
|
+============================+=========+==============================================+============+
|
|
| name | string | (optional) The name of the secret set by the | None |
|
|
| | | user. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| expiration | string | (optional) This is a timestamp in ISO 8601 | None |
|
|
| | | format ``YYYY-MM-DDTHH:MM:SSZ``. Once this | |
|
|
| | | time has past, the secret will no longer be | |
|
|
| | | available. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| algorithm | string | (optional) Metadata provided by a user or | None |
|
|
| | | system for informational purposes. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| bit_length | integer | (optional) Metadata provided by a user or | None |
|
|
| | | system for informational purposes. Value | |
|
|
| | | must be greater than zero. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| mode | string | (optional) Metadata provided by a user or | None |
|
|
| | | system for informational purposes. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| payload | string | (optional) The secret's data to be stored. | None |
|
|
| | | ``payload_content_type`` must also be | |
|
|
| | | supplied if payload is provided. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| payload_content_type | string | (optional) (required if payload is added) | None |
|
|
| | | The type and format of the secret data. The | |
|
|
| | | two supported types are ``text/plain`` and | |
|
|
| | | ``application/octet-stream``. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| payload_content_encoding | string | (optional) The encoding used to format the | None |
|
|
| | | payload provided. Currently only base64 is | |
|
|
| | | supported. This is required if content type | |
|
|
| | | provided has an encoding available. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| secret_type | string | (optional) Used to indicate the type of | ``opaque`` |
|
|
| | | 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. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
|
|
Request:
|
|
********
|
|
|
|
.. code-block:: javascript
|
|
|
|
POST /v1/secrets
|
|
Headers:
|
|
Content-Type: application/json
|
|
X-Project-Id: {project_id}
|
|
|
|
Content:
|
|
{
|
|
"name": "AES key",
|
|
"expiration": "2015-12-28T19:14:44.180394",
|
|
"algorithm": "aes",
|
|
"bit_length": 256,
|
|
"mode": "cbc",
|
|
"payload": "YmVlcg==",
|
|
"payload_content_type": "application/octet-stream",
|
|
"payload_content_encoding": "base64"
|
|
}
|
|
|
|
Response:
|
|
*********
|
|
|
|
.. code-block:: none
|
|
|
|
201 Created
|
|
|
|
{
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
|
|
}
|
|
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 201 | Successfully created a Secret |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 400 | Bad Request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 415 | Unsupported media-type |
|
|
+------+-----------------------------------------------------------------------------+
|
|
|
|
|
|
GET /v1/secrets/{uuid}
|
|
######################
|
|
Retrieves a secret's metadata or payload via uuid.
|
|
|
|
The return type of content, metadata or payload, is controlled by the Accept
|
|
header.
|
|
|
|
Accept Header Options:
|
|
**********************
|
|
|
|
* application/json - Returns secret metadata
|
|
* application/octet-stream - Returns secret payload
|
|
* text/plain - Returns secret payload
|
|
|
|
|
|
Metadata Request:
|
|
*****************
|
|
|
|
.. code-block:: none
|
|
|
|
GET /v1/secrets/{uuid}
|
|
Headers:
|
|
Accept: application/json
|
|
X-Project-Id: {project_id}
|
|
|
|
|
|
Metadata Response:
|
|
******************
|
|
|
|
.. code-block:: javascript
|
|
|
|
200 OK
|
|
|
|
{
|
|
"status": "ACTIVE",
|
|
"created": "2015-03-23T20:46:51.650515",
|
|
"updated": "2015-03-23T20:46:51.654116",
|
|
"expiration": "2015-12-28T19:14:44.180394",
|
|
"algorithm": "aes",
|
|
"bit_length": 256,
|
|
"mode": "cbc",
|
|
"name": "AES key",
|
|
"secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}",
|
|
"secret_type": "opaque",
|
|
"content_types": {
|
|
"default": "application/octet-stream"
|
|
}
|
|
}
|
|
|
|
Payload Request:
|
|
****************
|
|
|
|
.. code-block:: none
|
|
|
|
GET /v1/secrets/{uuid}
|
|
Headers:
|
|
Accept: application/octet-stream
|
|
X-Project-Id: {project_id}
|
|
|
|
|
|
Payload Response:
|
|
*****************
|
|
|
|
.. code-block:: none
|
|
|
|
200 OK
|
|
|
|
beer
|
|
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 200 | Successful request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 404 | Not Found |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 406 | Not Acceptable |
|
|
+------+-----------------------------------------------------------------------------+
|
|
|
|
.. _put_secrets:
|
|
|
|
PUT /v1/secrets/{uuid}
|
|
######################
|
|
|
|
Update a secret's payload by uuid
|
|
|
|
.. note::
|
|
|
|
This action can only be done for a secret that doesn't have a payload already
|
|
set.
|
|
|
|
Required Headers
|
|
****************
|
|
|
|
+------------------+---------------------------------------------------+------------+
|
|
| Name | Description | Default |
|
|
+==================+===================================================+============+
|
|
| Content-Type | Corresponds with the payload_content_type | text/plain |
|
|
| | attribute of a normal secret creation request. | |
|
|
+------------------+---------------------------------------------------+------------+
|
|
| Content-Encoding | Corresponds with the payload_content_encoding | None |
|
|
| | attribute of a normal secret creation request. | |
|
|
+------------------+---------------------------------------------------+------------+
|
|
|
|
Request:
|
|
********
|
|
|
|
.. code-block:: none
|
|
|
|
PUT /v1/secrets/{uuid}
|
|
Headers:
|
|
X-Project-Id: {project_id}
|
|
Content-Type: application/octet-stream
|
|
Content-Encoding: base64
|
|
|
|
Content:
|
|
YmxhaA==
|
|
|
|
Response:
|
|
*********
|
|
|
|
.. code-block:: none
|
|
|
|
204 No Content
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 204 | Successful request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 404 | Not Found |
|
|
+------+-----------------------------------------------------------------------------+
|
|
|
|
.. _delete_secrets:
|
|
|
|
DELETE /v1/secrets/{uuid}
|
|
#########################
|
|
|
|
Delete a secret by uuid
|
|
|
|
Request:
|
|
****************
|
|
|
|
.. code-block:: none
|
|
|
|
DELETE /v1/secrets/{uuid}
|
|
Headers:
|
|
X-Project-Id: {project_id}
|
|
|
|
Response:
|
|
****************
|
|
|
|
.. code-block:: none
|
|
|
|
204 No Content
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 204 | Successful request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 404 | Not Found |
|
|
+------+-----------------------------------------------------------------------------+
|
|
|
|
|
|
GET /v1/secrets/{uuid}/payload
|
|
##############################
|
|
Retrieve a secret's payload
|
|
|
|
Accept Header Options:
|
|
**********************
|
|
|
|
* application/octet-stream - Returns secret payload
|
|
* text/plain - Returns secret payload
|
|
|
|
Request:
|
|
********
|
|
|
|
.. code-block:: none
|
|
|
|
GET /v1/secrets/{uuid}/payload
|
|
Headers:
|
|
Accept: text/plain
|
|
X-Project-Id: {project_id}
|
|
|
|
Response:
|
|
*********
|
|
|
|
.. code-block:: none
|
|
|
|
200 OK
|
|
|
|
beer
|
|
|
|
HTTP Status Codes
|
|
*****************
|
|
|
|
+------+-----------------------------------------------------------------------------+
|
|
| Code | Description |
|
|
+======+=============================================================================+
|
|
| 200 | Successful request |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 404 | Not Found |
|
|
+------+-----------------------------------------------------------------------------+
|
|
| 406 | Not Acceptable |
|
|
+------+-----------------------------------------------------------------------------+
|