docs/books/modules/user-guide/enabling-ssl-tls-encryption.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-incoming-client-connections.adoc

[id='enabling-ssl-tls-encryption-{context}']
= Enabling SSL/TLS encryption

You can use SSL/TLS to encrypt an incoming connection from a client.

.Prerequisites

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

* A security certificate must be generated and 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 for client connections, then add one.
+
--
This `sslProfile` contains the locations of the private key and certificates that the router should use to encrypt connections from clients.

[options="nowrap",subs="+quotes"]
----
sslProfile {
    name: service-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 `listener` for this connection to use SSL/TLS to encrypt the connection.
+
--
This example configures a `normal` listener to encrypt connections from clients.

[options="nowrap",subs="+quotes"]
----
listener {
    host: 0.0.0.0
    port: 5672
    role: normal
    sslProfile: inter_router_tls
    requireSsl: yes
    ...
}
----
`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for client connections.

`requireSsl`:: Specify `true` to encrypt the connection with SSL/TLS.
--