diff options
Diffstat (limited to 'qpid/doc/book/src/SSL.xml')
| -rw-r--r-- | qpid/doc/book/src/SSL.xml | 180 |
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 & + Ruby Client (M4 and up) + </title> + <para> + Simply use amqps:// in the URL string as defined above + </para> + <!--h2--></section> + <!--h1--></section> +</section> |