<?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 guides through the details of configuration of Keystores and Trsustores
        required for enabling of SSL transport and Client Certificate Authentication on Broker ports.
        The details how to configure SSL on Broker ports are provided in <xref linkend="Java-Broker-Ports"/>.
    </para>

    <section role="h2" id="Java-Broker-SSL-Keystore">
        <title>Keystore Configuration</title>
        <para>
            A Keystore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">
            REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">
            Web Management Console</link>. Any number of Keystores can be configured on the Broker.
            SSL ports can be configured with different Keystores.
        </para>

        <para>The following Keystore managing operations are available from
        <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>:
        <itemizedlist>
            <listitem><para>A new Keystore can be added by clicking on "Add Key Store" button on the Broker tab.</para></listitem>
            <listitem><para>Keystore details can be viewed on the Keystore tab which is displayed after clicking
            on Keystore name in the Broker object tree or after clicking on Keystore row in Keystores grid on the Broker tab.</para></listitem>
            <listitem><para>Editing of Keystore can be performed by clicking on "Edit" button on the Keystore tab.
            Changing of Keystore name is unsupported at the moment. If changed Keystore is used by the Port
            the changes on Port object will take effect after Broker restart.</para></listitem>
            <listitem><para>An existing Keystore can be deleted by clicking on "Delete Key Store" button on Broker tab
            or hitting "Delete" button on the Keystore tab. Only unused Keystores can be deleted.
            The deletion of the Keystore configured on any Broker Port is not allowed.</para></listitem>
        </itemizedlist>
        </para>

        <para>
            The "Keystore certificate alias" field is an optional way of specifying which certificate the broker should use
            if the keystore contains multiple entries. Optionally "Key manager factory algorithm" and "Key store type" can
            be specified on Keystore creation.
        </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
            by adding a Trustore configured object and associating it with the SSL port.
            A Truststore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">
            REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">
            Web Management Console</link>. Any number of Trustores can be configured on the Broker.
            Multiple Trustores can be configured on Broker SSL Ports.
        </para>

        <para>The following Truststore managing operations are available from
        <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>:
        <itemizedlist>
            <listitem><para>A new Truststore can be added by clicking on "Add Trust Store" button on the Broker tab.</para></listitem>
            <listitem><para>Truststore details can be viewed on the Truststore tab which is displayed after clicking
            onto Truststore name in the Broker object tree or after clicking onto Truststore row in Truststores grid on the Broker tab.</para></listitem>
            <listitem><para>Trustore can be edited by clicking onto "Edit" button on the Trustore tab.
            Changing of Trustore name is unsupported at the moment.</para></listitem>
            <listitem><para>An existing Trustore can be deleted by clicking onto "Delete Trust Store" button
            on Broker tab or "Delete" button on the Truststore tab. Only unused Truststores can be deleted.
            The deletion of the Truststore configured on any Broker Port is not allowed.</para></listitem>
        </itemizedlist>
        </para>

        <para>When "Peers Only" option is selected for the Truststore it will allow logging in for the clients
        with the certificate exactly matching the certificate loaded in the Truststore database,
        thus, authenticating the connections with self signed certificates not nessesary signed by CA.
        </para>

        <para>"Trust manager factory algorithm" and "Trust store type" can
            be optionally specified for the Trustore.
        </para>

    </section>
</section>