QPID-6108: [Java Documentation] Refactor security/auth providers section into separate files to allow for convenient re-purposing of the document

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1635639 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 74 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml
new file mode 100644
index 0000000000..2924f2859c
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Configuration-Encryption.xml
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<section id="Java-Broker-Security-Configuration-Encryption">
+  <title>Configuration Encryption</title>
+  <para> The Broker is capable of encrypting 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
+      stronger encryption or delegating the storage of the key to an Enterprise Password Safe.</para>
+  </section>
+</section>