************************
Secret Types - Reference
************************

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.

The possible secret types are:

* ``symmetric`` - Used for storing byte arrays such as keys suitable for
  symmetric encryption.
* ``public`` - Used for storing the public key of an asymmetric keypair.
* ``private`` - Used for storing the private key of an asymmetric keypair.
* ``passphrase`` - Used for storing plain text passphrases.
* ``certificate`` - Used for storing cryptographic certificates such as X.509
  certificates.
* ``opaque`` - Used for backwards compatibility with previous versions of the
  API without typed secrets.  New applications are encouraged to specify one
  of the other secret types.

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 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 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
the command line using curl.

.. code-block:: bash

   # Create an encryption_key file with 256 bits of random data
   dd bs=32 count=1 if=/dev/urandom of=encryption_key

   # Encode the contents of the encryption key using base64 encoding
   KEY_BASE64=$(base64 < encryption_key)

   # Send a request to store the key in Barbican
   curl -vv -H "X-Auth-Token: $TOKEN" -H 'Accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{"name": "AES encryption key",
        "secret_type": "symmetric",
        "payload": "'"$KEY_BASE64"'",
        "payload_content_type": "application/octet-stream",
        "payload_content_encoding": "base64",
        "algorithm": "AES",
        "bit_length": 256,
        "mode": "CBC"}' \
   http://localhost:9311/v1/secrets | python -m json.tool

This should return a reference (URI) for the secret that was created:

.. code-block:: json

   {
     "secret_ref": "http://localhost:9311/v1/secrets/48d24158-b4b4-45b8-9669-d9f0ef793c23"
   }

We can use this reference to retrieve the secret metadata:

.. code-block:: bash

   curl -vv -H "X-Auth-Token: $TOKEN" -H 'Accept: application/json' \
   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:

.. code-block:: json

    {
        "algorithm": "AES",
        "bit_length": 256,
        "content_types": {
            "default": "application/octet-stream"
        },
        "created": "2015-04-08T06:24:16.600393",
        "creator_id": "3a7e3d2421384f56a8fb6cf082a8efab",
        "expiration": null,
        "mode": "CBC",
        "name": "AES encryption key",
        "secret_ref": "http://localhost:9311/v1/secrets/48d24158-b4b4-45b8-9669-d9f0ef793c23",
        "secret_type": "symmetric",
        "status": "ACTIVE",
        "updated": "2015-04-08T06:24:16.614204"
    }

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:

.. code-block:: bash

    # Retrieve the payload and save it to a file
   curl -vv -H "X-Auth-Token: $TOKEN" \
   -H 'Accept: application/octet-stream' \
   -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
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"
   }
