[spec] PKCS#11 Key Type Rotation

Change-Id: I200816b9f063ee23d40f312d655129e7961f24b4

specs/bobcat/hmac-key-type-rotation.rst

@@ -0,0 +1,128 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=========================
+PKCS#11 Key Type Rotation
+=========================
+
+https://blueprints.launchpad.net/barbican/+spec/pkcs11-key-type-rotatioin
+
+When new MKEK and HMAC keys are provisioned in the PKCS#11 device, the key type
+should be allowed to change.
+
+Problem Description
+===================
+
+Currently the `hsm rewrap_pkek` command in barbican-manage can be used to
+encrypt and hmac the Project KEKs in the database with a new MKEK and HMAC
+master keys.  However, the key types for the current (phasing out) keys are not
+stored in the database.  Because of this, it is not possible to change the key
+types during this rotation.
+
+Proposed Change
+===============
+
+Add new options to the barbican-manage cli tool to specify both the current and
+new key types.  Also save the key types as part of the key meta in the database
+for every pKEK entry. e.g.
+
+    barbican-manage hsm rewrap_pkek --old_encryption_key_id $ID \
+        --old_encryption_key_type $KEY_TYPE \
+        --old_hmac_key_id         $KEY_ID \
+        --old_hmac_key_type       $KEY_TYPE \
+        --encryption_key_id       $KEY_ID \
+        --encryption_key_type     $KEY_TYPE \
+        --hmac_key_id             $KEY_ID \
+        --hmac_key_type           $KEY_TYPE
+
+For backwards compatibility, the old key types should be requiered by the CLI
+if they can't be found in the database.
+
+Alternatives
+------------
+
+N/A
+
+Data model impact
+-----------------
+
+The model will have to be changed to allow for additional key metadata so the
+key type of the keys used to wrap the pkek can be stored for future use.
+
+REST API impact
+---------------
+
+N/A
+
+Security impact
+---------------
+
+N/A
+
+Notifications & Audit Impact
+----------------------------
+
+N/A
+
+Python and Command Line Client Impact
+-------------------------------------
+
+N/A
+
+Other end user impact
+---------------------
+
+N/A
+
+Performance Impact
+------------------
+N/A
+
+Other deployer impact
+---------------------
+
+N/A
+
+Developer impact
+----------------
+
+N/a
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  Douglas Mendizábal <dmendiza@redhat.com>
+
+Other contributors:
+  TBD
+
+Work Items
+----------
+
+
+Dependencies
+============
+
+N/A
+
+Testing
+=======
+
+Functional tests will be added to test the pKEK rewrap function.
+
+Documentation Impact
+====================
+
+N/A - The cli tool is self-documenting.
+
+References
+==========
+
+N/A