[spec] Add authentication to AES-CBC encryption

Change-Id: I7e8395792ef052750245845887ee38022a341d06

doc/source/index.rst

@@ -4,6 +4,14 @@
 Barbican Project Specifications
 ===============================
 
+Bobcat approved specs:
+
+.. toctree::
+     :glob:
+     :maxdepth: 1
+
+     specs/bobcat/*
+
 Train approved specs:
 
 .. toctree::

specs/bobcat/pkcs11-aes-cbc-authentication.rst

@@ -0,0 +1,165 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+===========================================================
+Add authentication to AES-CBC encryption in PKCS#11 backend
+===========================================================
+
+https://blueprints.launchpad.net/barbican/+spec/pkcs11-aes-cbc-authentication
+
+The PKCS#11 plugin backend can be configured to use one of several supported
+encryption mechanisms, including AES in both GCM and CBC modes.  GCM is the
+preferred mode because it provides Authenticated Encryption (AE) [1].
+
+However, not all PKCS#11 devices support this mechanism.  When CKM_AES_GCM is
+not available CKM_AES_CBC can be used, but it does not provide AE.
+
+This spec proposes a change to the CKM_AES_CBC encryption in the PKCS#11 plugin
+backend to provide a similar level of protection against ciphertext tampering
+when CKM_AES_GCM is not available.
+
+Problem Description
+===================
+
+An attacker with write access to the barbican database could modify the
+ciphertext for a secret and Barbican would not be able to detect that the
+ciphertext has been tampered with.  This is because AES-CBC encryption alone
+does not guarantee integrity.
+
+Proposed Change
+===============
+
+The AES-CBC encryption implementation in the PKCS#11 plugin backend would be
+changed to also compute an HMAC of the ciphertext.  Likewise, the decryption
+implementation would first check the validity of the ciphertext to be decrypted
+by first verifying the HMAC before starting the decryption process.
+
+The key used in the HMAC would be generated automatically on a per-project
+basis in a simliar fashion to the existing pKEK generation.
+
+We will have to ensure backwards compatibility with existing deployments.  One
+way of achieving this would be to provide a way to rotate the project hmac keys
+that can be used to calculate new HMACs for existing databases.  e.g.
+
+    barbican-manage hsm rotate_project_hmac $PROJECT_ID
+
+That would generate a new pHMAC key for that project and wrap all existing
+secrets in that project wit the new key.  The decrypt function will check HMACs
+when available, and just decrypt the ciphertext otherwise.
+
+For really large databases we could also have a `--all` flag that would rotate
+the pHMAC key for all projects.
+
+Alternatives
+------------
+
+One alternative is to do nothing and keep AES-CBC encryption as is and
+recommend that users configure barbican to use AES-GCM when available.
+
+For dealing with existing deployments, instead of migrating the data using
+barbican-manage, we could handle generating the pHMAC and hashing the secret
+when they are first accessed after this change is deployed.
+
+Data model impact
+-----------------
+
+We will need to store the calculated hmac for every secret that is encrypted,
+as well as information about the hmac key that was used.
+
+REST API impact
+---------------
+
+N/A
+
+Security impact
+---------------
+
+This change would improve the security of Barbican data at rest by guaranteeing
+the integrity of the secret ciphertext when not using AE.
+
+Notifications & Audit Impact
+----------------------------
+
+N/A
+
+Python and Command Line Client Impact
+-------------------------------------
+
+N/A
+
+Other end user impact
+---------------------
+
+When using the PKCS#11 backend with AES-CBC encryption, the plugin will be
+doing more work to encrypt and decrypt secrets since it will have to peform
+additional work to calculate or verify the hmac.
+
+Performance Impact
+------------------
+
+When using AES-CBC, encryption and decryption will be performing additional
+work to calculate and verify the hmac. For deployments using a Hardware
+Security Model, this would mean an additional call to the hsm for both
+encryption and decryption.
+
+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
+----------
+
+* Add models for pHMAC and add relationships to the Project and Secret models.
+* Create database migration files to store additional data such as the pHMAC
+  keys for each project and HMACs and key metadata for every secret.
+* Modify the PKCS#11 plugin backend to generate and verify HMACs during encrypt
+  and decrypt respectively
+* Implement pHMAC rotation in barbican-manage
+
+Dependencies
+============
+
+N/A
+
+Testing
+=======
+
+This would be a good opportunity to finally add PKCS#11 functional tests by
+adding Zuul jobs that test Barbican with the PKCS#11 plugin using SoftHSM.
+This would include both Tempest tests for functionality as well as Grenade
+tests for backwards compatibility.
+
+Unit tests will be added to prove that the new encrypt and decrypt functions
+are working as expected, as well as unit tests for backwars compatibility.
+
+Documentation Impact
+====================
+
+The new sub-command in barbican-manage will be self-documenting, but we will
+need to update the Barbican security model.
+
+References
+==========
+
+[1] https://blog.cryptographyengineering.com/2012/05/19/how-to-choose-authenticated-encryption/