QPID-6162 : add documentation

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

3 files changed, 60 insertions, 11 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml b/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml
index 09f011ba2b..6a6fe11296 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!--
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]><!--
 
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
index 8fbd2fd1b6..0ce5375d02 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE entities [
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
 <!ENTITY %  entities SYSTEM  "commonEntities.xml">
 %entities;
 ]>
@@ -193,9 +195,7 @@ com.sun.security.jgss.accept {
   <section id="Java-Broker-Security-ScramSha-Providers">
     <title>SCRAM SHA Providers</title>
     <para>The SCRAM SHA Providers uses the Broker configuration itself to store the database of
-      users. (Unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
-        >Plain</link> and <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
-        >Base64MD5</link> providers that follow, there is no separate password file). The users'
+      users. The users'
       passwords are stored as salted SHA digested password. This can be further encrypted using the
       facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"
       />.</para>
@@ -206,13 +206,28 @@ com.sun.security.jgss.accept {
       Management.</para>
   </section>
 
+  <section id="Java-Broker-Security-Plain-Provider">
+    <title>Plain</title>
+    <para>The Plain Provider uses the Broker configuration itself to store the database of
+      users (unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
+        >PlainPasswordFile</link>, there is no separate password file).  As the name suggests, the
+        user data (including password) is not hashed in any way.  In order to provide encryption, the
+        facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"/> must
+        be used.</para>
+    <para>For this provider user credentials can be added, removed or changed using
+      Management.</para>
+        </section>
+        
   <section id="Java-Broker-Security-PlainPasswordFile-Provider">
-    <title>Plain Password File</title>
+    <title>Plain Password File <emphasis>(Deprecated)</emphasis></title>
+    <para><emphasis>This provider is deprecated and will be removed in a future release.  The
+    <link linkend="Java-Broker-Security-Plain-Provider">Plain</link> provider should be used
+    instead.</emphasis></para>
     <para> The PlainPasswordFile Provider uses local file to store and manage user credentials. When
       creating an authentication provider the path to the file needs to be specified. If specified
       file does not exist an empty file is created automatically on Authentication Provider
       creation. On Provider deletion the password file is deleted as well.</para>
-    <para>For these providers user credentials can be added, removed or changed using
+    <para>For this provider user credentials can be added, removed or changed using
       Management.</para>
 
     <section>
@@ -228,14 +243,34 @@ guest:guest
     </section>
   </section>
 
+  
+  <section id="Java-Broker-Security-MD5-Provider">
+    <title>MD5 Provider</title>
+    
+    <para> MD5 Provider  uses the Broker configuration itself to store the database of
+      users (unlike the <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
+        >Base64MD5 Password File</link>, there is no separate password file). Rather than store the
+        unencrypted user password (as the Plain provider does) it instead stores the MD5 password 
+        digest.  This can be further encrypted using the
+      facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"
+      />.</para>
+      <para>For this provider user credentials can be added, removed or changed using
+      Management.</para>
+  </section>
+  
   <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider">
-    <title>Base64MD5 Password File</title>
+    <title>Base64MD5 Password File <emphasis>(Deprecated)</emphasis></title>
+    <para><emphasis>This provider is deprecated and will be removed in a future release.  The
+    <link linkend="Java-Broker-Security-MD5-Provider">MD5</link> provider should be used
+    instead.</emphasis></para>
     <para> Base64MD5PasswordFile Provider uses local file to store and manage user credentials
       similar to PlainPasswordFile but instead of storing a password the MD5 password digest encoded
       with Base64 encoding is stored in the file. When creating an authentication provider the path
       to the file needs to be specified. If specified file does not exist an empty file is created
       automatically on Authentication Provider creation. On Base64MD5PasswordFile Provider deletion
       the password file is deleted as well.</para>
+      <para>For this provider user credentials can be added, removed or changed using
+      Management.</para>
     <section>
       <title>Base64MD5 File Format</title>
       <para> The user credentials are stored on the single file line as user name and user password
@@ -243,4 +278,5 @@ guest:guest
         file must not be modified externally whilst the Broker is running.</para>
     </section>
   </section>
-</section>
+ </section>
+
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
index d4248ca83a..f6af69cacf 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
@@ -1,4 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!--
 
  Licensed to the Apache Software Foundation (ASF) under one
@@ -46,16 +48,22 @@
                 <listitem><para><link linkend="Java-Broker-Security-ScramSha-Providers"
                             >ScramSha</link>: authenticate users against credentials stored in a
                         local database</para></listitem>
+                <listitem><para><link linkend="Java-Broker-Security-Plain-Provider"
+                            >Plain</link>: authenticate users against credentials stored in a local 
+                            database.</para></listitem>
                 <listitem><para><link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
                             >PlainPasswordFile</link>: authenticate users against credentials stored
                         in plain text in a local file.</para></listitem>
+                <listitem><para><link linkend="Java-Broker-Security-MD5-Provider"
+                            >MD5</link>: authenticate users against credentials
+                        stored in a local database.</para></listitem>
                 <listitem><para><link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
                             >Base64MD5PasswordFile</link>: authenticate users against credentials
                         stored encoded in a local file.</para></listitem>
             </itemizedlist>
-            <para>The last three providers offer user management facilities too, that is, users can
+            </para>
+            <para>The last five providers offer user management facilities too, that is, users can
                 be created, deleted and passwords reset.</para>
-        </para>
     </section>
 
     <section id="Java-Broker-Management-Managing-Authentication-Providers-Attributes">