doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Keystores.xml

<?xml version="1.0"?>
<!--

 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Management-Managing-Keystores">
    <title>Keystores</title>
    <para>A <link linkend="Java-Broker-Concepts-Keystores">Keystore</link> is required by a Port in
        order to use SSL for messaging and/or management.</para>
    <para>The Broker supports a number of different keystore types. These are described
        below.</para>
    <para>The key material may be held by the Broker itself (held inline within the configuration)
        or you may use references to files on the server's file system. Whichever mechanism is
        chosen it is imperative to ensure that private key material remains confidential.</para>
    <section xml:id="Java-Broker-Management-Managing-Keystores-Types">
        <title>Types</title>
        <para>The following keystore types are supported. <itemizedlist>
                <listitem>
                    <para><emphasis>File Key Store</emphasis>. This type accepts the standard JKS
                        keystore format undertood by Java and Java tools such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleKeytool}">keytool</link>.</para>
                    <para>If the keystore contains multiple keys, it is possible to indicate which
                        certificate is to be used by specifying an alias. If no alias is specified
                        the first certificate found in the keystore will be used.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Non Java Key Store</emphasis>. A Non Java Keystore accepts key
                        material in PEM and DER file formats. With this store type it is necessary
                        to provide the private key, which must not be protected by password,
                        certificate and optionally a file containing intermediate
                        certificates.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Auto Generated Self Signed</emphasis> has the ability to
                        generate a self signed certificate and produce a truststore
                        suitable for use by an application using the Apache Qpid JMS client for AMQP 0-9-1/0-10.</para>
                    <para>The use of self signed certficates is not recommended for production
                        use.</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Keystores-Attributes">
        <title>Attributes</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Name the keystore</emphasis>. Used to identify the
                        keystore.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The following attributes apply to <emphasis>File Key Stores</emphasis> only.</para>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Keystore path</emphasis>. File Key Stores only. Path to keystore
                        file</para>
                </listitem>
                <listitem>
                    <para><emphasis>Keystore password</emphasis>. Password used to secure the keystore<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 Broker implementation. If
                                using the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleKeytool}">keytool</link> utility, note
                                that this means the argument to the <option>-keypass</option> option
                                must match the <option>-storepass</option> option. </para>
                        </important></para>
                </listitem>
                <listitem>
                    <para><emphasis>Certificate Alias</emphasis>. An optional way of specifying
                        which certificate the broker should use if the keystore contains multiple
                        entries.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Manager Factory Algorithm</emphasis>.In keystores the have more
                        than one certificate, the alias identifies the certificate to be
                        used.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Key Store Type</emphasis>. Type of Keystore.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The following attributes apply to <emphasis>Non Java Key Stores</emphasis>
            only.</para>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Private Key</emphasis>. The private key in DER or PEM format.
                        This file must not be password protected.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Certificate</emphasis>. The cerificate in DER or PEM
                        format.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Intermediates Certificates </emphasis>. Optional. Intermediate
                        cerificates in PEM or DER format.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The following attributes apply to <emphasis>Auto Generated Self Signed</emphasis>
            only.</para>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Algorithm</emphasis>. Optional. Algorithm used to generate the
                        self-signed certificate.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Signature Algorithm </emphasis>. Optional. The name of signature
                        algorithm.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Key Length</emphasis>. Optional. Length of the key in
                        bits.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Duration</emphasis>. Optional. Validility period in
                        months.</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Keystores-Children">
        <title>Children</title>
        <para>None</para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Keystores-Lifecycle">
        <title>Lifecycle</title>
        <para>Not supported</para>
    </section>
</section>