diff options
Diffstat (limited to 'doc/book/src/java-broker/Java-Broker-Security-SSL.xml')
| -rw-r--r-- | doc/book/src/java-broker/Java-Broker-Security-SSL.xml | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/book/src/java-broker/Java-Broker-Security-SSL.xml b/doc/book/src/java-broker/Java-Broker-Security-SSL.xml new file mode 100644 index 0000000000..e415065a84 --- /dev/null +++ b/doc/book/src/java-broker/Java-Broker-Security-SSL.xml @@ -0,0 +1,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> |