diff --git a/doc/source/api/reference/secret_types.rst b/doc/source/api/reference/secret_types.rst index 4db207aee..1b0a33360 100644 --- a/doc/source/api/reference/secret_types.rst +++ b/doc/source/api/reference/secret_types.rst @@ -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" + }