Add more types to the orders resource¶
https://blueprints.launchpad.net/barbican/+spec/api-orders-add-more-types
Barbican’s orders resource is used to generate secrets on behalf of clients. Currently (as of Icehouse M2) only specific symmetric key secrets can be generated. This blueprint addresses how the orders resources can be modified to generate other useful secret types, such as asymmetric key-pairs.
Problem Description¶
Barbican is currently lacking generation support for following secret types which is highly expected from a Key Manager:
There are three main types of secret information that could be generated by Barbican via the Orders resource:
- Key:
Symmetric encryption keys: AES, 3DES, Camellia, RC4.
Other types of keys: HMAC, byte stream
- Asymmetric:
RSA, DSA, EC.
Can include public and private keys, and a passphrase
- Certificate:
Generation by CSR signing by CA.
Generation by Barbican and its back-end plug-in using different parameters.
Proposed Change¶
This is a multi phase initiative as described below:
1. Enhance Barbican crypto plug-in framework to support generation of different types of secrets. (Completed)
Make appropriate changes to the Order data model to hold required parameters.
Enhance Orders REST API to support Key and Asymmetric secrets.
- Enhance Orders REST API to support Certificate type secrets which includes
API changes to support CSR post.
API changes to support post or certificate parameters.
Barbican core subsystem to integrate with CA.
Barbican event subsystem to emit events for certificate life-cycle.
Alternatives¶
None.
Data model impact¶
Barbican Order model has to be enhanced to support these requirements. Following new fields will need to be added in the model:
- Type (String): This field will represent the order type. Allowed options are
key, asymmetric and certificates
- Meta (Text): This field will hold JSON string and store all meta attributes
for secrets.
- container_id: An optional field depending on generated artifacts, a particular
type of secret can have multiple sub secrets. Such secrets requires Container object to group multiple secrets. e.g. Private Key, Public Key and Passphrase for a asymmetric key.
Note: Either the container_id or the existing secret_id will be filled out once the order is ACTIVE, depending on the type of secret generated by the order.
REST API impact¶
The ordering resource allows for the generation of secret material by Barbican. The ordering object encapsulates the work flow and history for the creation of a secret. This interface is implemented as an asynchronous process since the time to generate a secret can vary depending on the type of secret.
Resource Structure:
{
"type": "--type--",
"meta": {
"name": "--name--",
"algorithm": "--algorithm--",
"bit_length": --bit_length--,
"mode": "--mode--",
"pass_phrase": "--pass_phrase--",
"expiration": "--expiration--",
"payload_content_type": "--type--"
}
}
Note: Structure for meta is not yet decided for type certificate.
Required Attribute:
type (string)
Type of the secret, supported options are key, asymmetric and certificate:
meta (string)
Describes additional information regarding the secret:
meta.name (string)
Human readable name for the secret:
meta.algorithm (string)
Cryptographic algorithm type used to generate the secret. e.g. aes, 3des, hmacsha1, hmacsha256,hmacsha384, hmacsha512, rsa and dsa:
meta.bit_length (int)
The bit-length of the secret.
Optional Attribute:
meta.mode (string)
The type/mode of the algorithm associated with the secret information:
meta.pass_phrase (string)
Pass phrase to be associated with secret. Used in conjunction when type is asymmetric:
meta.expiration (string)
The expiration date for the secret in ISO-8601 format. Once the secret has expired, it will no longer be returned by the API or agent. If this field is not supplied, then the secret has no expiration date:
meta.payload_content_type (string)
API¶
Order
Create Order: POST /{tenant_id}/orders
Example 01 - Symmetric key generation:
Request:
POST /v1/{tenant_id}/orders
{
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "aes",
"bit_length": 256,
"mode": "cbc",
"expiration": "2015-02-28T19:14:44.180394",
"payload_content_type": "application/octet-stream"
}
}
Response:
Status: 201 Created
{
"order_ref": "http://localhost:9311/v1/1234/orders/daf3c6de-095f-46a8-94ec-65ec0d98eb68"
}
Example 02 - Asymmetric key generation:
Request:
POST /v1/{tenant_id}/orders
{
"type": "asymmetric",
"meta": {
"name": "secretname",
"algorithm": "RSA",
"bit_length": 2048,
"expiration": "2015-02-28T19:14:44.180394",
"payload_content_type": "application/octet-stream"
}
}
Response:
Status: 201 Created
{
"order_ref": "http://localhost:9311/v1/1234/orders//a8957047-16c6-4b05-ac57-8621edd0e9ee"
}
Example 03 - Certificate generation:
Request: (TBD)
Response: (TBD)
List Orders: GET /{tenant_id}/orders
List orders per tenant:
Request:
GET /v1/{tenant_id}/orders
Response:
Status: 200 OK
{
"orders": [
{
"status": "ACTIVE",
"secret_ref": "http://localhost:9311/v1/12345/secrets/bf2b33d5-5347-4afb-9009-b4597f415b7f",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "key",
"meta": {
"name": "secretname",
"algorithm": "AES",
"bit_length": 256,
"mode": "cbc",
"expiration": "2015-02-28T19:14:44.180394",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/1234/orders/daf3c6de-095f-46a8-94ec-65ec0d98eb68"
},
{
"status": "ACTIVE",
"container_ref": "http://localhost:9311/v1/12345/containers/fa71b143-f10e-4f7a-aa82-cc292dc33eb5",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"type": "asymmetric",
"meta": {
"name": "secretname",
"algorithm": "RSA",
"bit_length": 2048,
"expiration": "2015-02-28T19:14:44.180394",
"payload_content_type": "application/octet-stream"
},
"order_ref": "http://localhost:9311/v1/1234/orders//a8957047-16c6-4b05-ac57-8621edd0e9ee"
}
]
}
Note: There is no change to the existing “limit” and “offset” filter parameters.
Get Order: GET /{tenant_id}/orders/{order_id}
Get order by order_id:
Request:
GET /v1/{tenant_id}/orders/{order_id}
Response:
Status: 200 OK
{
"type": "asymmetric",
"meta": {
"name": "secretname",
"algorithm": "RSA",
"bit_length": 2048,
"expiration": "2015-02-28T19:14:44.180394",
"payload_content_type": "application/octet-stream"
},
"status": "ACTIVE",
"container_ref": "http://localhost:9311/v1/12345/containers/fa71b143-f10e-4f7a-aa82-cc292dc33eb5",
"updated": "2013-06-28T18:29:37.058718",
"created": "2013-06-28T18:29:36.001750",
"order_ref": "http://localhost:9311/v1/1234/orders//a8957047-16c6-4b05-ac57-8621edd0e9ee"
}
Security impact¶
None
Notifications & Audit Impact¶
None.
Other end user impact¶
Barbican-python client will need to be enhanced to accommodate API changes.
Performance Impact¶
None
Other deployer impact¶
None.
Developer impact¶
None.
Implementation¶
Assignee(s)¶
Arvind Tiwari (atiwari) is leading this feature enhancement.
Work Items¶
Enhance crypto plug-in framework to support secret generation for different types. (atiwari, DONE)
Data migration to add Type, Meta and container_id in the Orders Model. (atiwari, DONE)
Enhance Order REST API to support key and asymmetric order type. (atiwari, IN_PROGRESS, https://review.openstack.org/#/c/87405/)
Enhance Order REST API to support certificate order type. (TBD)
Enhance Barbican python client to support key and asymmetric order type. (TBD)
Enhance Barbican python client to support certificate order type. (TBD)
Dependencies¶
None
Testing¶
Need to add unit testing for the new order types.
This change has to be backwards compatible by allowing the current order contract to be used to generate symmetric keys, in addition to the new way outlined in this blueprint.
Documentation Impact¶
- Order API request and response structure has to be explained in the docs.
https://github.com/cloudkeep/barbican/wiki/Application-Programming-Interface#orders-resource
Barbican WADL and developer guide will be update for this API change.
