doc/book/src/old/SSL.xml

<?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>