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 retrieve the secret payload data for each individual 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 similar to this value.
alg	string	Selects all secrets with algorithm similar to this value.
mode	string	Selects all secrets with mode similar to this value.
bits	integer	Selects all secrets with bit_length equal to this value.
secret_type	string	Selects all secrets with secret_type equal to this value.
acl_only	boolean	Selects all secrets with an ACL that contains the user. Project scope is ignored.
created	string	Date filter to select all secrets with created matching the specified criteria. See Date Filters below for more detail.
updated	string	Date filter to select all secrets with updated matching the specified criteria. See Date Filters below for more detail.
expiration	string	Date filter to select all secrets with expiration matching the specified criteria. See Date Filters below for more detail.
sort	string	Determines the sorted order of the returned list. See Sorting below for more detail.

Date Filters:

The values for the created, updated, and expiration parameters are comma-separated lists of time stamps in ISO 8601 format. The time stamps can be prefixed with any of these comparison operators: gt: (greater-than), gte: (greater-than-or-equal), lt: (less-than), lte: (less-than-or-equal).

For example, to get a list of secrets that will expire in January of 2020:

GET /v1/secrets?expiration=gte:2020-01-01T00:00:00,lt:2020-02-01T00:00:00

Sorting:

The value of the sort parameter is a comma-separated list of sort keys. Supported sort keys include created, expiration, mode, name, secret_type, status, and updated.

Each sort key may also include a direction. Supported directions are :asc for ascending and :desc for descending. The service will use :asc for every key that does not include a direction.

For example, to sort the list from most recently created to oldest:

GET /v1/secrets?sort=created:desc

Request:

GET /v1/secrets?offset=1&limit=2&sort=created
Headers:
    Accept: application/json
    X-Auth-Token: {keystone_token}
    (or X-Project-Id: {project id})

Response:

{
    "next": "http://{barbican_host}:9311/v1/secrets?limit=2&offset=3",
    "previous": "http://{barbican_host}:9311/v1/secrets?limit=2&offset=0",
    "secrets": [
        {
            "algorithm": null,
            "bit_length": null,
            "content_types": {
                "default": "application/octet-stream"
            },
            "created": "2015-04-07T03:37:19.805835",
            "creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
            "expiration": null,
            "mode": null,
            "name": "opaque octet-stream base64",
            "secret_ref": "http://{barbican_host}:9311/v1/secrets/{uuid}",
            "secret_type": "opaque",
            "status": "ACTIVE",
            "updated": "2015-04-07T03:37:19.808337"
        },
        {
            "algorithm": null,
            "bit_length": null,
            "content_types": {
                "default": "application/octet-stream"
            },
            "created": "2015-04-07T03:41:02.184159",
            "creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
            "expiration": null,
            "mode": null,
            "name": "opaque random octet-stream base64",
            "secret_ref": "http://{barbican_host}:9311/v1/secrets/{uuid}",
            "secret_type": "opaque",
            "status": "ACTIVE",
            "updated": "2015-04-07T03:41:02.187823"
        }
    ],
    "total": 5
}

Response Attributes

Name	Type	Description
secrets	list	Contains a list of secrets. The attributes in the secret objects are the same as for an individual secret.
total	integer	The total number of secrets available to the user.
next	string	A HATEOAS 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 HATEOAS 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 entity. If the payload attribute is not included in the request, then only the metadata for the secret is created, and a subsequent PUT request is required.

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 UTC timestamp in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ. If set, the secret will not be available after this time.	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 included.	None
payload_content_type	string	(optional) (required if payload is included) The media type for the content of the payload. For more information see Secret Types <../reference/secret_types>	None
payload_content_encoding	string	(optional) (required if payload is encoded) The encoding used for the payload to be able to include it in the JSON request. Currently only base64 is supported.	None
secret_type	string	(optional) Used to indicate the type of secret being stored. For more information see Secret Types <../reference/secret_types>	opaque

Request:

POST /v1/secrets
Headers:
    Content-Type: application/json
    X-Auth-Token: <token>

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
403	Forbidden. The user has been authenticated, but is not authorized to create a secret. This can be based on the user's role or the project's quota.
415	Unsupported media-type

GET /v1/secrets/{uuid}

Retrieves a secret's metadata.

Request:

GET /v1/secrets/{uuid}
Headers:
    Accept: application/json
    X-Auth-Token: {token}
    (or X-Project-Id: {project_id})

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:

Warning

DEPRECATION WARNING: Previous releases of the API allowed the payload to be retrieved from this same endpoint by changing the Accept header to be one of the values listed in the content_types attribute of the Secret metadata. This was found to be problematic in some situations, so new applications should make use of the /v1/secrets/{uuid}/payload <secret_payload> endpoint instead.

GET /v1/secrets/{uuid}
Headers:
    Accept: application/octet-stream
    X-Auth-Token: <token>

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}

Add the payload to an existing metadata-only secret, such as one made by sending a POST /v1/secrets request that does not include the payload attribute.

Note

This action can only be done for a secret that doesn't have a payload.

Headers

Name	Description	Default
Content-Type	Corresponds with the payload_content_type attribute of a normal secret creation request.	text/plain
Content-Encoding	(optional) Corresponds with the payload_content_encoding attribute of a normal secret creation request.	None

Request:

PUT /v1/secrets/{uuid}
Headers:
    X-Auth-Token: <token>
    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-Auth-Token: <token>

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:

When making a request for a secret's payload, you must set the accept header to one of the values listed in the content_types attribute of a secret's metadata.

Request:

GET /v1/secrets/{uuid}/payload
Headers:
    Accept: text/plain
    X-Auth-Token: <token>

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