Creating a branch for experimenting with some ideas for JMS client.rajith_jms_client

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

1 files changed, 180 insertions, 0 deletions

diff --git a/qpid/doc/book/src/SSL.xml b/qpid/doc/book/src/SSL.xml
new file mode 100644
index 0000000000..a9a5cb953a
--- /dev/null
+++ b/qpid/doc/book/src/SSL.xml
@@ -0,0 +1,180 @@
+<?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><title>
+      SSL
+    </title>
+
+    <section role="h1" id="SSL-SSLHowto"><title>
+            SSL How to
+          </title>
+
+          <section role="h2" id="SSL-C-5Cbroker-28M4andup-29"><title>
+            C++ broker (M4 and up)
+          </title>
+          <itemizedlist>
+            <listitem><para>You need to get a certificate signed by a CA, trusted by your
+            client.
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>If you require client authentication, the clients certificate
+            needs to be signed by a CA trusted by the broker.
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Setting up the certificates for testing.
+              <itemizedlist>
+                <listitem><para>For testing purposes you could use the <xref linkend="qpid_gtstd"/> to setup your certificates.
+                </para></listitem>
+                <listitem><para>In summary you need to create a root CA and import it to
+                the brokers certificate data base.
+                </para></listitem>
+                <listitem><para>Create a certificate for the broker, sign it using the
+                root CA and then import it into the brokers certificate data
+                base.
+                </para></listitem>
+              </itemizedlist>
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Load the acl module using --load-module or if loading more
+            than one module, copy ssl.so to the location pointed by
+            --module-dir
+              
+                <programlisting>
+Ex if running from source. ./qpidd --load-module /libs/ssl.so
+</programlisting>
+              
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Specify the password file (a plain text file with the
+            password), certificate database and the brokers certificate name
+            using the following options
+              
+                <programlisting>
+Ex ./qpidd ... --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain
+</programlisting>
+              
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>If you require client authentication you need to add
+            --ssl-require-client-authentication as a command line argument.
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Please note that the default port for SSL connections is
+            5671, unless specified by --ssl-port
+            </para></listitem>
+          </itemizedlist><para>
+            Here is an example of a broker instance that requires SSL client
+            side authenticaiton
+          </para>
+            <programlisting>
+./qpidd ./qpidd --load-module /libs/ssl.so --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain --ssl-require-client-authentication
+</programlisting>
+	  <!--h2--></section>
+          <section role="h2" id="SSL-JavaClient-28M4andup-29"><title>
+            Java Client (M4 and up)
+          </title>
+          <itemizedlist>
+            <listitem><para>This guide is for connecting with the Qpid c++ broker.
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Setting up the certificates for testing. In summary,
+              <itemizedlist>
+                <listitem><para>You need to import the trusted CA in your trust store and
+                keystore
+                </para></listitem>
+                <listitem><para>Generate keys for the certificate in your key store
+                </para></listitem>
+                <listitem><para>Create a certificate request using the generated keys
+                </para></listitem>
+                <listitem><para>Create a certficate using the request, signed by the
+                trusted CA.
+                </para></listitem>
+                <listitem><para>Import the signed certificate into your keystore.
+                </para></listitem>
+              </itemizedlist>
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>Pass the following JVM arguments to your client.
+              
+                <programlisting>
+-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks
+   -Djavax.net.ssl.keyStorePassword=password
+   -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
+   -Djavax.net.ssl.trustStorePassword=password
+</programlisting>
+              
+            </para></listitem>
+          </itemizedlist>
+	  <!--h2--></section>
+
+	  <section role="h2" id="SSL-.NetClient-28M4andup-29"><title>
+            .Net Client (M4 and up)
+          </title>
+          <itemizedlist>
+            <listitem><para>If the Qpid broker requires client authentication then you
+            need to get a certificate signed by a CA, trusted by your client.
+            </para></listitem>
+          </itemizedlist><para>
+            Use the connectSSL instead of the standard connect method of the
+            client interface.
+          </para><para>
+            connectSSL signature is as follows:
+          </para>
+            <programlisting>
+public void connectSSL(String host, int port, String virtualHost, String username, String password, String serverName, String certPath, bool rejectUntrusted)
+</programlisting>
+          <para>
+            Where
+          </para><itemizedlist>
+            <listitem><para>host: Host name on which a Qpid broker is deployed
+            </para></listitem>
+            <listitem><para>port: Qpid broker port
+            </para></listitem>
+            <listitem><para>virtualHost: Qpid virtual host name
+            </para></listitem>
+            <listitem><para>username: User Name
+            </para></listitem>
+            <listitem><para>password: Password
+            </para></listitem>
+            <listitem><para>serverName: Name of the SSL server
+            </para></listitem>
+          </itemizedlist><itemizedlist>
+            <listitem><para>certPath: Path to the X509 certificate to be used when the
+            broker requires client authentication
+            </para></listitem>
+            <listitem><para>rejectUntrusted: If true connection will not be established
+            if the broker is not trusted (the server certificate must be
+            added in your truststore)
+            </para></listitem>
+          </itemizedlist>
+	  <!--h2--></section>
+
+	  <section role="h2" id="SSL-Python-26RubyClient-28M4andup-29"><title>
+            Python &amp;
+            Ruby Client (M4 and up)
+          </title>
+          <para>
+            Simply use amqps:// in the URL string as defined above
+          </para>
+	  <!--h2--></section>
+	<!--h1--></section>
+</section>