openstack/barbican
Code Issues Proposed changes

Document public secret type

Browse Source 
Adds documentation for public secret types.  Add two examples of storing
public secrets, one with a POST followed by PUT, and one with a single
POST.  The second example is incomplete until bug 1441866 is fixed.

Change-Id: I5c892d1b09e6bc0cb155c5591b12f409d3c86419
This commit is contained in:
Douglas Mendizábal 2015-04-08 17:48:22 -05:00 committed by Douglas Mendizábal
parent c78e72957a
commit 6dbc87dbde
1 changed files with 158 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
doc/source/api/reference/secret_types.rst
View File

@ -2,7 +2,7 @@
Secret Types - Reference
************************
Every Secret in Barbican has a type. Secret types are used to describe
Every secret in Barbican has a type. Secret types are used to describe
different kinds of secret data that are stored in Barbican. The type for a
particular secret is listed in the secret's metadata as the ``secret_type``
attribute.
@ -20,18 +20,18 @@ The possible secret types are:
API without typed secrets. New applications are encouraged to specify one
of the other secret types.
Symmetric Keys
##############
Symmetric
#########
The ``symmetric`` secret type is used to store byte arrays of sensitive data,
such as keys that are used for symmetric encryption. The content type used
with symmetric keys is ``application/octet-stream``. When storing a symmetric
secret with a single POST request, the data must be encoded so that it may
be included inside the JSON body of the request. In this case, the
such as keys that are used for symmetric encryption. The content-type used
with symmetric secrets is ``application/octet-stream``. When storing a
symmetric secret with a single POST request, the data must be encoded so that
it may be included inside the JSON body of the request. In this case, the
content encoding of ``base64`` can be used.
Example
*******
Example 1.1
***********
Create an encryption key for use in AES-256-CBC encryption and store it in
Barbican. First, we'll see how this can be done in a single POST request from
@ -58,7 +58,7 @@ the command line using curl.
"mode": "CBC"}' \
http://localhost:9311/v1/secrets | python -m json.tool
This should return a reference (URI) for the Secret that was created:
This should return a reference (URI) for the secret that was created:
.. code-block:: json
@ -74,7 +74,7 @@ We can use this reference to retrieve the secret metadata:
http://localhost:9311/v1/secrets/48d24158-b4b4-45b8-9669-d9f0ef793c23 |
python -m json.tool
The metadata will list the available content types for the symmetric secret:
The metadata will list the available content-types for the symmetric secret:
.. code-block:: json
@ -95,7 +95,7 @@ The metadata will list the available content types for the symmetric secret:
"updated": "2015-04-08T06:24:16.614204"
}
The ``content_types`` attribute describes the content types that can be used
The ``content_types`` attribute describes the content-types that can be used
to retrieve the payload. In this example, there is only the default content
type of ``application/octet-stream``. We can use it to retrieve the payload:
@ -107,7 +107,152 @@ type of ``application/octet-stream``. We can use it to retrieve the payload:
-o retrieved_key \
http://localhost:9311/v1/secrets/48d24158-b4b4-45b8-9669-d9f0ef793c23/payload
The *retrieved_key* file now contains the byte array we started with. Note
The ``retrieved_key`` file now contains the byte array we started with. Note
that barbican returned the byte array in binary format, not base64. This is
because the ``payload_content_encoding`` is only used when submitting the secret
to barbican.
Public
######
The ``public`` secret type is used to store the public key of an asymmetric
keypair. For example, a public secret can be used to store the public key
of an RSA keypair. Currently, there is only one file format accepted for
public secrets: A DER-encoded ``SubjectPublicKeyInfo`` structure as defined by
X.509 RFC 5280 that has been Base64 encoded with a PEM header and footer.
This is the type of public key that is generated by the ``openssl`` tool by
default. The content-type used with public secrets is
``application/octet-stream``. When storing a public secret with a single POST
request, the contents of the file must be encoded since JSON does not accept
newline characters. In this case, the contents of the file must be Base64
encoded and the content encoding of ``base64`` can be used.
Example 2.1
***********
Create an RSA keypair and store the public key in Barbican. For this example,
we will be using a metadata-only POST followed by a PUT.
.. code-block:: bash
# Create the RSA keypair
openssl genrsa -out private.pem 2048
# Extract the public key
openssl rsa -in private.pem -out public.pem -pubout
# Submit a metadata-only POST
curl -vv -H "X-Auth-Token: $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"name": "RSA Public Key",
"secret_type": "public",
"algorithm": "RSA"}' \
http://localhost:9311/v1/secrets | python -m json.tool
This should return a reference (URI) for the secret that was created:
.. code-block:: json
200 OK
{
"secret_ref": "http://localhost:9311/v1/secrets/cd20d134-c229-417a-a753-86432ad13bad"
}
We can use this reference to add the payload with a PUT request:
.. code-block:: bash
curl -vv -X PUT -H "X-Auth-Token: $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/octet-stream' \
--data-binary @public.pem \
http://localhost:9311/v1/secrets/cd20d134-c229-417a-a753-86432ad13bad
The server should respond with a 2xx response to indicate that the PUT request
was processed successfully:
.. code-block:: json
204 - No Content
Now we should be able to request the metadata and see the new content-type
listed there:
.. code-block:: bash
curl -vv -H "X-Auth-Token: $TOKEN" \
-H 'Accept: application/json' \
http://localhost:9311/v1/secrets/cd20d134-c229-417a-a753-86432ad13bad |
python -m json.tool
.. code-block:: json
{
"algorithm": "RSA",
"bit_length": null,
"content_types": {
"default": "application/octet-stream"
},
"created": "2015-04-08T21:45:59.239976",
"creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
"expiration": null,
"mode": null,
"name": "RSA Public Key",
"secret_ref": "http://localhost:9311/v1/secrets/cd20d134-c229-417a-a753-86432ad13bad",
"secret_type": "public",
"status": "ACTIVE",
"updated": "2015-04-08T21:52:57.523969"
}
Finally, we can use the default content-type listed in ``content_types`` to
retrieve the public key:
.. code-block:: bash
curl -vv -H "X-Auth-Token: $TOKEN" \
-H 'Accept: application/octet-stream' \
-o retrieved_public.pem \
http://localhost:9311/v1/secrets/cd20d134-c229-417a-a753-86432ad13bad/payload
The ``retrieved_public.pem`` file now has the same contents as the public.pem
file we started with.
Example 2.2
***********
Create an RSA keypair and store the public key in Barbican. For this example
we will be using a single POST request.
.. code-block:: bash
# Create the RSA keypair
openssl genrsa -out private.pem 2048
# Extract the public key
openssl rsa -in private.pem -out public.pem -pubout
# Base64 encode the contents of the public key
PUB_BASE64=$(base64 < public.pem)
curl -vv -H "X-Auth-Token: $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"name": "RSA Public Key",
"secret_type": "public",
"payload": "'"$PUB_BASE64"'",
"payload_content_type": "application/octet-stream",
"payload_content_encoding": "base64",
"algorithm": "RSA"}' \
http://localhost:9311/v1/secrets | python -m json.tool
This should return a reference (URI) for the secret that was created.
.. code-block:: json
200 OK
{
"secret_ref": "http://localhost:9311/v1/secrets/d553f0ac-c79d-43b4-b165-32594b612ad4"
}