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
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE entities [
<!ENTITY % entities SYSTEM "commonEntities.xml">
%entities;
]>
<!--
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 id="Java-Broker-Security-SSL">
<title>SSL</title>
<para>
This section will show how to use SSL to enable secure
connections between an AMQP message client and the broker.
</para>
<section role="h2" id="SSL-Keystore">
<title>Keystore Configuration</title>
<para>
The broker configuration file (config.xml) needs to be updated to include the required SSL keystore
configuration, an example of which can be found below.
</para>
<example>
<title>Configuring an SSL Keystore</title>
<programlisting><![CDATA[
<connector>
...
<ssl>
<enabled>true</enabled>
<port>5671</port>
<sslOnly>false</sslOnly>
<keyStorePath>/path/to/keystore.ks</keyStorePath>
<keyStorePassword>keystorepass</keyStorePassword>
<certAlias>alias<certAlias>
</ssl>
...
<connector>]]></programlisting>
</example>
<para>
The certAlias element is an optional way of specifying which certificate the broker should use
if the keystore contains multiple entries.
</para>
<para>
The sslOnly element controls whether the broker will <emphasis role="bold">only</emphasis> bind
the configured SSL port(s) or will also bind the non-SSL port(s). Setting sslOnly to true will
disable the non-SSL ports.
</para>
<important>
<para>
The password of the certificate used by the Broker <emphasis role="bold">must</emphasis>
match the password of the keystore itself. This is a restriction of the Qpid Broker
implementation. If using the <ulink url="&oracleKeytool;">keytool</ulink> utility,
note that this means the argument to the <option>-keypass</option> option must match
the <option>-storepass</option> option.
</para>
</important>
</section>
<section role="h2" id="SSL-Truststore-ClientCertificate">
<title>Truststore / Client Certificate Authentication</title>
<para>
The SSL trustore and related Client Certificate Authentication behaviour can be configured with
additional configuration as shown in the example below, in which the broker requires client
certificate authentication.
</para>
<example>
<title>Configuring an SSL Truststore and client auth</title>
<programlisting><![CDATA[
<connector>
...
<ssl>
...
<trustStorePath>/path/to/truststore.ks</trustStorePath>
<trustStorePassword>truststorepass</trustStorePassword>
<needClientAuth>true</needClientAuth>
<wantClientAuth>false</wantClientAuth>
...
</ssl>
...
<connector>]]></programlisting>
</example>
<para>
The needClientAuth and wantClientAuth elements allow control of whether the client must present an
SSL certificate. Only one of these elements is needed but both may be used at the same time.
A socket's client authentication setting is one of three states: required (needClientAuth = true),
requested (wantClientAuth = true), or none desired (both false, the default). If both elements are
set to true, needClientAuth takes precedence.
</para>
<para>
When using Client Certificate Authentication it may be desirable to use the External Authentication
Manager, for details see <xref linkend="ExternalAuthManager"></xref>
</para>
</section>
</section>
|
