1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
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>
|
