Open Stack

Hello folks,

As we dig into the REST flows for Barbican, we are thinking of tweaking things a bit as detailed below.  Feedback welcome, thanks in advance.

Starting with an easy one: 
We propose changing from 'orders' to 'requests'...so to request that Barbican create a new secret (or start a process to generate a secret) clients would issue a 'request'. This seems more natural, and a bit less overused than 'orders'. 

Now getting into more details on the secrets/requests process...

A conundrum we've been mulling is how to consistently deal with the application/json content-type for the CRUD of secrets and requests/orders, versus other mime-types that a secret request/retrieval might be needed in.

Per the current blueprint:
When we GET a secret via UUID, if we just specify an 'Accept' header of 'application/json' we plan to return just the metadata about the secret, with no actual decrypted secret content. This metadata would include a listing of available content-types. Hence a follow up GET call for the same secret, but with an Accept of one of the available content-types would decrypt the secret info and return it in the specified format. 

This amounts to a two-step process to retrieve a secret, and provides the ability to zero in on a specific format you need (e.g. pem format, octet stream for binary, etc.). 

Proposed tweak:
To be consistent with the two-step retrieve process, we propose that the secret creation process be two step too.

So the first step would be to POST to secrets with metadata about the secret:
- name (optional)
- algorithm - ex: aes
- bit-length - ex: 256
- cypher-type - ex: CBC, XTS, etc.
- mime-type - ex: application/pem, application/base64, application/octet-stream, etc.
This POST would return the URI/UUID to the new secret, but without encrypted data stored.

The next step would be to provide the actual plain-text to encrypt/store in Barbican, via a follow up PUT call to the new secret, with the Accept header set to the mime-type above (say application/pem). This data would then be encrypted and stored by Barbican. To address Malini's concern about wrecking systems already using a key to encrypt their data, we may only allow one such PUT request to happen per secret.

When a GET is performed for this secret with Accept set to 'application/json', the metadata-only content described above would be seen. In particular, the 'content-types' group would have content such as this:

'content-types': {
  'default': 'application/pem',
  'x509': 'application/x509'
}

Where 'default' is always the mime-type specified in the original secrets POST. The other entries would represent alternative mime-type forms available for the secret information (as determined by Barbican), based on the default mime-type. 

To get the decrypted secret data, a GET request with one of these 'content-types' would produce the secret in that format. 

Does this all make sense, and would it be acceptable to folks? 

As usual, comments/feedback welcome!

Thanks,
John