3c935a82d1
This is the start of a reworking of our docs around the secrets API. There will be a number of follow-up patches before this document will be considered complete. Until this document is considered complete, I'm not adding this page to the table of contents. Also, to limit individual CR size, I've tossed TODOs on the areas that will be worked on in future CRs. Change-Id: I8599628d51f4b5aae9ec1b8fd76f419d5b38bdcc
138 lines
8.1 KiB
ReStructuredText
138 lines
8.1 KiB
ReStructuredText
***********************
|
|
Secrets API - Reference
|
|
***********************
|
|
|
|
GET /secrets
|
|
############
|
|
Lists a project's secrets.
|
|
|
|
The list of secrets can be filtered by the parameters passed in via the URL.
|
|
|
|
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. |
|
|
+--------+---------+----------------------------------------------------------------+
|
|
|
|
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. |
|
|
+----------+---------+--------------------------------------------------------------+
|
|
|
|
|
|
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
|
|
#############
|
|
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.`` | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| 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. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
| 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. | |
|
|
+----------------------------+---------+----------------------------------------------+------------+
|
|
|
|
TODO(jvrbanac): Finish this section
|
|
|
|
GET /secrets/{uuid}
|
|
###################
|
|
Retrieves a secret's metadata by uuid
|
|
|
|
TODO(jvrbanac): Finish this section
|
|
|
|
DELETE /secrets/{uuid}
|
|
######################
|
|
|
|
Delete a secret by uuid
|
|
|
|
TODO(jvrbanac): Finish this section
|
|
|
|
GET /secrets/{uuid}/payload
|
|
###########################
|
|
Retrieve a secret's payload
|
|
|
|
TODO(jvrbanac): Finish this section
|
|
|
|
PUT /secrets/{uuid}/payload
|
|
###########################
|
|
Update a secret's payload
|
|
|
|
TODO(jvrbanac): Finish this section
|