doc/java-broker/src/docbkx/management/managing/Java-Broker-Management-Managing-Truststores.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-Truststores">
    <title>Truststores</title>
    <para> A <link linkend="Java-Broker-Concepts-Truststores">Truststore</link> is required by a
        Port in order to SSL client authentication. Some authentication provides also use a
        truststore when connecting to authentication systems that are protected by a private issuer
        SSL certificate.</para>
    <section xml:id="Java-Broker-Management-Managing-Truststores-Types">
        <title>Types</title>
        <para>The following truststore types are supported. <itemizedlist>
                <listitem>
                    <para><emphasis>File Trust Store</emphasis>. This type accepts the standard JKS
                        truststore format understood by Java and Java tools such as <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleKeytool}">keytool</link>.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Non Java Trust Store</emphasis>. A non java trust store accepts key
                        material in PEM and DER file formats. Either a path to the certificate on the server can be specified using the file:// protocol or the certificate can be uploaded with the data:// protocol</para>
                </listitem>
                <listitem>
                    <para><emphasis>Managed Certificate Store</emphasis>. This type accepts key
                        material in PEM and DER file formats. Contrary to the Non Java Trust Store this store allows the user to add multiple certificates and stores them in the broker configuration.</para>
                </listitem>
                <listitem>
                    <para><emphasis>Site Specific Trust Store</emphasis>. This type will download a certificate from the provided SSL/TLS enabled URL. Note that you must specify both the protocol and the port. Example: https://example.com:443</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Truststores-Attributes">
        <title>Attributes</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Name the truststore</emphasis>. Used to identify the
                        truststore.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The following attributes apply to <emphasis>File Trust Stores</emphasis> only.</para>
        <para>
            <itemizedlist>

                <listitem>
                    <para><emphasis>Path</emphasis>. Path to truststore file</para>
                </listitem>
                <listitem>
                    <para><emphasis>Truststore password</emphasis>. Password used to secure the truststore<important>
                            <para> The password of the certificate used by the Broker <emphasis role="bold">must</emphasis> match the password of the keystore
                                itself. </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>
                <listitem>
                    <para><emphasis>Peers only</emphasis>. When "Peers Only" option is selected for
                        the Truststore it will allow authenticate only those clients that present a
                        certificate exactly matching a certificate contained within the Truststore
                        database.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The following attributes apply to <emphasis>Non Java Trust Stores</emphasis>
            only.</para>
        <para>
            <itemizedlist>
                <listitem>
                    <para><emphasis>Certificates</emphasis>. The cerificate(s) in DER or PEM
                        format.</para>
                </listitem>
            </itemizedlist>
        </para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Truststores-Children">
        <title>Children</title>
        <para>None</para>
    </section>
    <section xml:id="Java-Broker-Management-Managing-Truststores-Lifecycle">
        <title>Lifecycle</title>
        <para>Not supported</para>
    </section>
</section>