From cc2ba9f942385cd6a45b8c2796617fa2c3e1266c Mon Sep 17 00:00:00 2001
From: Keith Wall <kwall@apache.org>
Date: Thu, 9 Oct 2014 21:52:34 +0000
Subject: QPID-6108: [Java Broker Documentation] Add HA operational log
 messages, section related to configuration encryption and SCRAM-SHA
 providers.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1630597 13f79535-47bb-0310-9956-ffa450edef68
---
 ...va-Broker-Security-Configuration-Encryption.xml | 54 +++++++++++++++++++---
 1 file changed, 48 insertions(+), 6 deletions(-)

(limited to 'qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml')

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
index 4e7b95a3d7..9fe2a4683e 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
@@ -23,10 +23,52 @@
 
 <section id="Java-Broker-Security-Configuration-Encryption">
   <title>Configuration Encryption</title>
-  <para>
-    QPID-6017 : TODO
-    Describe mechanism available to secure secrets within the configuration.
-    Mention that full strength JVM required.
-  </para>
-
+  <para> The Broker is capable of encypting passwords and other security items stored in the
+    Broker's configuration. This is means that items such as keystore/truststore passwords, JDBC
+    passwords, and LDAP passwords can be stored in the configure in a form that is difficult to
+    read.</para>
+  <para>The Broker ships with an encryptor implementation called <literal>AESKeyFile</literal>. This
+    uses a securely generated random key of 256bit<footnote><para>Java Cryptography Extension (JCE)
+        Unlimited Strength required</para></footnote> to encrypt the secrets stored within a key
+    file. Of course, the key itself must be guarded carefully, otherwise the passwords encrypted
+    with it may be compromised. For this reason, the Broker that the file's permissions allow the
+    file to be read exclusively by the user account used for running the Broker.</para>
+  <important>
+    <para>If the keyfile is lost or corrupted, the secrets will be irrecoverable.</para>
+  </important>
+  <section id="Java-Broker-Security-Configuration-Encryption-Configuration">
+    <title>Configuration</title>
+    <para>To use <literal>AESKeyFile</literal>, first stop the Broker, then edit the Broker's
+      configuration file ${QPID_WORK}/config.json. Insert a Broker attribute called
+        <literal>confidentialConfigurationEncryptionProvider</literal> with value
+        <literal>AESKeyFile</literal>. On restarting the Broker, it will generate a keyfile in
+      location <literal>${QPID_WORK}/.keys/</literal>. Any existing passwords contained with the
+      configuration will be automatically encrypted, as will any new or changed ones in
+      future.</para>
+    <example>
+      <title>Enanbling password encryption</title>
+      <screen>
+ {
+  "id" : "3f183a59-abc3-40ad-8e14-0cac9de2cac4",
+  "name" : "${broker.name}",
+  "confidentialConfigurationEncryptionProvider" : "AESKeyFile",
+  ....
+ }
+      </screen>
+    </example>
+    <para>Note that passwords stored by the Authentication Providers <link
+        linkEnd="Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link> and.
+        <link linkEnd="Java-Broker-Security-Base64MD5PasswordFile-Provider">PlainPasswordFile</link>
+      with the external password files are <emphasis>not</emphasis> encrypted by the key. Use the
+      Scram Authentication Managers instead; these make use of the Configuration Encryption when
+      storing the users' passwords. </para>
+  </section>
+  <section id="Java-Broker-Security-Configuration-Encryption-Alternate-Implementations">
+    <title>Alternate Implementations</title>
+    <para>If the <literal>AESKeyFile</literal> encryptor implementation does not meet the needs of
+      the user, perhaps owing to the security standards of their institution, the
+        <literal>ConfigurationSecretEncrypter</literal> interface is designed as an extension point.
+      Users may implement their own implementation of ConfigurationSecretEncrypter perhaps to employ
+      stonger encryption or delegating the storage of the key to an Enterprise Password Safe.</para>
+  </section>
 </section>
-- 
cgit v1.2.1