docs/books/modules/user-guide/connecting-using-mutual-ssl-tls-authentication.adoc

////
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
////

// Module is included in the following assemblies:
//
// securing-outgoing-connections.adoc

[id='connecting-using-mutual-ssl-tls-authentication-{context}']
= Connecting using mutual SSL/TLS authentication

You can connect to an external AMQP container (such as a broker) using mutual SSL/TLS authentication. With this method, the router, acting as a client, provides a certificate to the external AMQP container so that it can verify the router's identity.

.Prerequisites

* An X.509 Certificate Authority (CA) must exist for the router.

* A security certificate must be generated for the router and be signed by the CA.

.Procedure

include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]

. If the router does not contain an `sslProfile` that defines the private keys and certificates to connect to the external AMQP container, then add one.
+
--
This `sslProfile` contains the locations of the private key and certificates that the router should use to authenticate with its peer.

[options="nowrap",subs="+quotes"]
----
sslProfile {
    name: broker-tls
    certFile: /etc/pki/tls/certs/tls.crt
    caCertFile: /etc/pki/tls/certs/ca.crt
    privateKeyFile: /etc/pki/tls/private/tls.key
    password: file:/etc/pki/tls/private/password.txt
    ...
}
----
`name`:: A unique name that you can use to refer to this `sslProfile`.

`certFile`:: The absolute path to the file containing the public certificate for this router.

`caCertFile`:: The absolute path to the CA certificate that was used to sign the router's certificate.

`privateKeyFile`:: The absolute path to the file containing the private key for this router's public certificate.
+
[NOTE]
====
Ensure that the `qdrouterd` or root user can access the private key. For example:

[options="nowrap",subs="+quotes"]
----
chmod 0600 /etc/pki/tls/private/tls.key
chown qdrouterd /etc/pki/tls/private/tls.key
----
====

//`password`
include::{FragmentDir}/fragment-password-description.adoc[]
--

. Configure the `connector` for this connection to use the `sslProfile` that you created.
+
--
[options="nowrap",subs="+quotes"]
----
connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    sslProfile: broker-tls
    saslMechanisms: EXTERNAL
    ...
}
----
`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for the inter-router network.
--