add readme about barbican security issues

Using Barbican with Keystone authentication has some known
problems.  Specifically, the problme is that Keystone now uses PKI
tokens, which are too long for the Barbican protocol to handle in
its current configuration.  This patch delivers a readme file to
document these issues for the end-user.

Signed-off-by: Keith Holman <Keith.Holman@windriver.com>
Signed-off-by: Bruce Ashfield <bruce.ashfield@windriver.com>

1 files changed, 69 insertions, 0 deletions

diff --git a/meta-openstack/Documentation/README.barbican b/meta-openstack/Documentation/README.barbican
new file mode 100644
index 0000000..59eedea
--- /dev/null
+++ b/meta-openstack/Documentation/README.barbican
@@ -0,0 +1,69 @@
+Summary
+=======
+
+This document is intended to provide an overview of the implementation
+details with the current release of Barbican.
+
+
+Limitation 1: No authorization required for retrieving secrets
+=============================================================
+
+The current implementation of Barbican allows secrets that are stored using
+authentication to be retrieved without authentication.  Thus, all stored
+secrets are available to anyone with access to the system.
+
+An example of this, can be seen from running the following commands, using
+the barbicanclient:
+$ barbican --os-username admin --os-password not-valid secret store \
+ -n mysecret -p 'top secret data' -t 'text/plain'
+returns: a failure as the username and password are not correct
+$ barbican --os-username admin --os-password password secret store \
+ -n mysecret -p 'top secret data' -t 'text/plain'
+returns: [the address retrieve the secret]
+$ barbican --no-auth secret get --decrypt [address returned above]
+returns: top secret data 
+
+
+Limitation 2: Integration with Keystone authentication
+=======================================================
+Introduced in the Grizzly release of OpenStack, Keystone by default uses
+PKI tokens as opposed to UUID tokens.  PKI tokens are much larger then UUID
+tokens (> 6000 bytes versus 16 bytes).  Without changing the maximum packet
+size, PKI tokens are too large to fit into a Barbican request packet.  The
+uWSGI maximum packet size has been increased to the maximum of 65355 bytes
+(from the default of 4096 bytes) in order to support PKI tokens by default.
+The larger PKI token size will increase the network load due to the larger
+packets that are sent when authentication is enabled.
+
+When using Barbican with Keystone authentication it is a known problem that
+due to the varying length of the PKI token secret size for Barbican has no
+fixed maximum.  There are two solutions to this problem:
+
+* Don't use Keystone authentication when storing secrets with Barbican
+* Change Keystone to revert back using UUID tokens instead of PKI tokens
+  (See next section below for the security implications of doing this)
+
+
+Changing Keystone to use UUID tokens
+====================================
+
+PKI tokens increase security by increasing the token size versus using UUID
+tokens. Reverting back to UUID tokens fixes the problem described above.
+However, the disadvantage is that you loose the security PKI tokens provide
+to all resources that use Keystone for authentication purposes, including
+Barbican.
+
+To have Keystone use UUID as tokens, change the bitbake recipe 
+(python-keystone_git.bb) by setting the TOKEN_FORMAT variable to a value of
+"UUID" and recompile. ie. Change the line TOKEN_FORMAT ?= "PKI" to
+TOKEN_FORMAT="UUID" in the python-keyston_git.bb file.
+
+
+Security Implications
+=====================
+
+* UUID tokens are shorter in length then UUID tokens, thus they are more
+  susceptible to brute force attacks.
+* Changing Keystone to use UUID tokens affects all system services that
+  rely on Keystone (for example, the Horizon web interface)
+