barbican/doc/source/api/reference/secrets.rst

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.

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 /v1/secrets

Creates a secret

Attributes

Attribute Name	Type	Description	Default
name	string	(optional) The name of the secret set by the user.	None
expiration	string	(optional) This is a timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. Once this time has past, the secret will no longer be available.	None
algorithm	string	(optional) Metadata provided by a user or system for informational purposes.	None
bit_length	integer	(optional) Metadata provided by a user or system for informational purposes. Value must be greater than zero.	None
mode	string	(optional) Metadata provided by a user or system for informational purposes.	None
payload	string	(optional) The secret's data to be stored. payload_content_type must also be supplied if payload is provided.	None
payload_content_type	string	(optional) (required if payload is added) The type and format of the secret data. The two supported types are text/plain and application/octet-stream.	None
payload_content_encoding	string	(optional) The encoding used to format the payload provided. Currently only base64 is supported. This is required if content type provided has an encoding available.	None
secret_type	string	(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.	opaque

Request:

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:

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:

GET /v1/secrets/{uuid}
Headers:
    Accept: application/json
    X-Project-Id: {project_id}

Metadata Response:

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:

GET /v1/secrets/{uuid}
Headers:
    Accept: application/octet-stream
    X-Project-Id: {project_id}

Payload Response:

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 /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 attribute of a normal secret creation request.	text/plain
Content-Encoding	Corresponds with the payload_content_encoding attribute of a normal secret creation request.	None

Request:

PUT /v1/secrets/{uuid}
Headers:
    X-Project-Id: {project_id}
    Content-Type: application/octet-stream
    Content-Encoding: base64

Content:
YmxhaA==

Response:

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 /v1/secrets/{uuid}

Delete a secret by uuid

Request:

DELETE /v1/secrets/{uuid}
Headers:
    X-Project-Id: {project_id}

Response:

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:

GET /v1/secrets/{uuid}/payload
Headers:
    Accept: text/plain
    X-Project-Id: {project_id}

Response:

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