Chapter 9. Securing network connections You can configure AMQ Interconnect to communicate with clients, routers, and brokers in a secure way by authenticating and encrypting the router's connections. AMQ Interconnect supports the following security protocols: SSL/TLS for certificate-based encryption and mutual authentication SASL for authentication with mechanisms You configure SSL/TLS, SASL (or a combination of both) to secure any of the following: Secure connections between routers Secure incoming client connections Secure outgoing connections 9.1. Securing connections between routers Connections between interior routers should be secured with SSL/TLS encryption and authentication (also called mutual authentication) to prevent unauthorized routers (or endpoints pretending to be routers) from joining the network. SSL/TLS mutual authentication requires an X.509 Certificate Authority (CA) with individual certificates generated for each interior router. Connections between the interior routers are encrypted, and the CA authenticates each incoming inter-router connection. This procedure describes how to secure a connection between two interior routers using SSL/TLS mutual authentication. Prerequisites An X.509 Certificate Authority must exist for the interior routers. A security certificate must be generated for each router and be signed by the CA. An inter-router connection must exist between the routers. For more information, see Section 8.1, "Connecting routers" . Procedure On the router that establishes the connection, do the following: Open the /etc/qpid-dispatch/qdrouterd.conf . If the router does not contain an sslProfile that defines the private keys and certificates for the inter-router network, then add one. This sslProfile contains the locations of the private key and certificates that the router uses to authenticate with its peer. 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 the router uses to authenticate incoming clients. 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: password The password to unlock the certificate key. You do not need to specify this if the certificate key does not have a password. By using different prefixes, you can specify the password several different ways depending on your security requirements: Specify the absolute path to a file that contains the password. This is the most secure option, because you can set permissions on the file that contains the password. For example: Specify an environment variable that stores the password. Use this option with caution, because the environment of other processes is visible on certain platforms. For example: Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: Configure the inter-router connector for this connection to use the sslProfile that you created. sslProfile The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network. On the router that listens for the connection, do the following: Open the /etc/qpid-dispatch/qdrouterd.conf . If the router does not contain an sslProfile that defines the private keys and certificates for the inter-router network, then add one. Configure the inter-router listener for this connection to use SSL/TLS to secure the connection. sslProfile The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network. authenticatePeer Specify yes to authenticate the peer interior router's identity. requireSsl Specify yes to encrypt the connection with SSL/TLS. saslMechanisms Specify EXTERNAL to enable X.509 client certificate authentication. 9.2. Securing incoming client connections You can use SSL/TLS and SASL to provide the appropriate level of security for client traffic into the router network. You can use the following methods to secure incoming connections to a router from AMQP clients, external containers, or edge routers: Enable SSL/TLS encryption Enable SSL/TLS client authentication Enable user name and password authentication Integrate with Kerberos 9.2.1. 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 Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. 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. 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 the router uses to authenticate incoming clients. 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: password The password to unlock the certificate key. You do not need to specify this if the certificate key does not have a password. By using different prefixes, you can specify the password several different ways depending on your security requirements: Specify the absolute path to a file that contains the password. This is the most secure option, because you can set permissions on the file that contains the password. For example: Specify an environment variable that stores the password. Use this option with caution, because the environment of other processes is visible on certain platforms. For example: Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: 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. 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. 9.2.2. Enabling SSL/TLS client authentication In addition to SSL/TLS encryption, you can also use SSL/TLS to authenticate an incoming connection from a client. With this method, a clients must present its own X.509 certificate to the router, which the router uses to verify the client's identity. Prerequisites SSL/TLS encryption must be configured. For more information, see Section 9.2.1, "Enabling SSL/TLS encryption" . The client must have an X.509 certificate that it can use to authenticate to the router. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. Configure the listener for this connection to use SSL/TLS to authenticate the client. This example adds SSL/TLS authentication to a normal listener to authenticate incoming connections from a client. The client will only be able to connect to the router by presenting its own X.509 certificate to the router, which the router will use to verify the client's identity. authenticatePeer Specify yes to authenticate the client's identity. saslMechanisms Specify EXTERNAL to enable X.509 client certificate authentication. 9.2.3. Enabling user name and password authentication You can use the SASL PLAIN mechanism to authenticate incoming client connections against a set of user names and passwords. You can use this method by itself, or you can combine it with SSL/TLS encryption. Prerequisites The cyrus-sasl-plain plugin is installed. Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed. To see a list of Cyrus SASL plugins in Red Hat Enterprise Linux, use the yum search cyrus-sasl command. To install a Cyrus SASL plugin, use the yum install <plugin> command. Procedure If necessary, add the user names and passwords to the SASL database. This example adds a new user (user1@example.com) to the SASL database (qdrouterd.sasldb): Note The full user name is the user name you entered plus the domain name ( <user-name> @ <domain-name> ). Providing a domain name is not required when you add a user to the database, but if you do not provide one, a default domain will be added automatically (the hostname of the machine on which the tool is running). Ensure that the qdrouterd process can read the SASL database. If the qdrouterd process runs as an unprivileged user, you might need to adjust the permissions or ownership of the SASL database so that the router can read it. This example makes the qdrouterd user the owner of the SASL database: Open the /etc/sasl2/qdrouterd.conf configuration file. This example shows a /etc/sasl2/qdrouterd.conf configuration file: Verify that the mech_list attribute contains the PLAIN mechanism. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. In the router section, specify the path to the SASL configuration file. saslConfigDir The absolute path to the SASL configuration file that contains the path to the SASL database that stores the user names and passwords. Configure the listener for this connection to authenticate clients using SASL PLAIN. This example configures basic user name and password authentication for a listener . In this case, no SSL/TLS encryption is being used. 9.2.4. Integrating with Kerberos If you have implemented Kerberos in your environment, you can use it with the GSSAPI SASL mechanism to authenticate incoming connections. Prerequisites A Kerberos infrastructure must be deployed in your environment. In the Kerberos environment, a service principal of amqp/<hostname>@<realm> must be configured. This is the service principal that AMQ Interconnect uses. The cyrus-sasl-gssapi package must be installed on each client and the router host machine. Procedure On the router's host machine, open the /etc/sasl2/qdrouterd.conf configuration file. This example shows a /etc/sasl2/qdrouterd.conf configuration file: Verify the following: The mech_list attribute contains the GSSAPI mechanism. The keytab attribute points to the location of the keytab file. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. In the router section, specify the path to the SASL configuration file. saslConfigDir The absolute path to the SASL configuration file that contains the path to the SASL database. For each incoming connection using Kerberos for authentication, set the listener to use the GSSAPI mechanism. 9.3. Securing outgoing connections If a router is configured to create connections to external AMQP containers (such as message brokers), you can use the following methods to secure the connection: Connect using SSL/TLS encryption (one-way authentication) Connect using SSL/TLS mutual authentication Connect using user name and password authentication (with or without SSL/TLS encryption) 9.3.1. Connecting using one-way SSL/TLS authentication You can connect to an external AMQP container (such as a broker) using one-way SSL/TLS. With this method, the router validates the external AMQP container's server certificate to verify its identity. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. If the router does not contain an sslProfile that defines a certificate that can be used to validate the external AMQP container's identity, then add one. name A unique name that you can use to refer to this sslProfile . caCertFile The absolute path to the CA certificate used to verify the external AMQP container's identity. Configure the connector for this connection to use SSL/TLS to validate the server certificate received by the broker during the SSL handshake. This example configures a connector to a broker. When the router connects to the broker, it will use the CA certificate defined in the broker-tls sslProfile to validate the server certificate received from the broker. sslProfile The name of the sslProfile that defines the certificate to use to validate the external AMQP container's identity. 9.3.2. 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 Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. 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. 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 the router uses to authenticate incoming clients. 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: password The password to unlock the certificate key. You do not need to specify this if the certificate key does not have a password. By using different prefixes, you can specify the password several different ways depending on your security requirements: Specify the absolute path to a file that contains the password. This is the most secure option, because you can set permissions on the file that contains the password. For example: Specify an environment variable that stores the password. Use this option with caution, because the environment of other processes is visible on certain platforms. For example: Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: Configure the connector for this connection to use the sslProfile that you created. sslProfile The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network. 9.3.3. Connecting using user name and password authentication You can use the SASL PLAIN mechanism to connect to an external AMQP container that requires a user name and password. You can use this method by itself, or you can combine it with SSL/TLS encryption. Prerequisites The cyrus-sasl-plain plugin is installed. Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed. To see a list of Cyrus SASL plugins in Red Hat Enterprise Linux, use the yum search cyrus-sasl command. To install a Cyrus SASL plugin, use the yum install <plugin> command. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. Configure the connector for this connection to provide user name and password credentials to the external AMQP container. saslPassword The password to connect to the peer. By using different prefixes, you can specify the password several different ways depending on your security requirements: Specify the absolute path to a file that contains the password. This is the most secure option, because you can set permissions on the file that contains the password. For example: Specify an environment variable that stores the password. Use this option with caution, because the environment of other processes is visible on certain platforms. For example: Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example:

Commands:
sslProfile { name: inter-router-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 }
chmod 0600 /etc/pki/tls/private/tls.key chown qdrouterd /etc/pki/tls/private/tls.key
password: file:/etc/qpid-dispatch-certs/inter-router/password.txt
password: env:CERT_PASSWORD
password: pass:mycertpassword
connector { host: 192.0.2.1 port: 5001 role: inter-router sslProfile: inter-router-tls }
listener { host: 0.0.0.0 port: 5001 role: inter-router sslProfile: inter_router_tls authenticatePeer: yes requireSsl: yes saslMechanisms: EXTERNAL }
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 }
chmod 0600 /etc/pki/tls/private/tls.key chown qdrouterd /etc/pki/tls/private/tls.key
password: file:/etc/qpid-dispatch-certs/inter-router/password.txt
password: env:CERT_PASSWORD
password: pass:mycertpassword
listener { host: 0.0.0.0 port: 5672 role: normal sslProfile: inter_router_tls requireSsl: yes }
listener { host: 0.0.0.0 port: 5672 role: normal sslProfile: service-tls requireSsl: yes authenticatePeer: yes saslMechanisms: EXTERNAL }
sudo saslpasswd2 -c -f qdrouterd.sasldb -u example.com user1
sudo chown qdrouterd /var/lib/qdrouterd/qdrouterd.sasldb
pwcheck_method: auxprop auxprop_plugin: sasldb sasldb_path: qdrouterd.sasldb mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
router { mode: interior id: Router.A saslConfigDir: /etc/sasl2/ }
listener { host: 0.0.0.0 port: 5672 authenticatePeer: yes saslMechanisms: PLAIN }
pwcheck_method: auxprop auxprop_plugin: sasldb sasldb_path: qdrouterd.sasldb keytab: /etc/krb5.keytab mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
router { mode: interior id: Router.A saslConfigDir: /etc/sasl2/ }
listener { host: 0.0.0.0 port: 5672 authenticatePeer: yes saslMechanisms: GSSAPI }
sslProfile { name: broker-tls caCertFile: /etc/qpid-dispatch-certs/ca.crt }
connector { host: 192.0.2.1 port: 5672 role: route-container sslProfile: broker-tls }
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 }
chmod 0600 /etc/pki/tls/private/tls.key chown qdrouterd /etc/pki/tls/private/tls.key
password: file:/etc/qpid-dispatch-certs/inter-router/password.txt
password: env:CERT_PASSWORD
password: pass:mycertpassword
connector { host: 192.0.2.1 port: 5672 role: route-container sslProfile: broker-tls saslMechanisms: EXTERNAL }
connector { host: 192.0.2.1 port: 5672 role: route-container saslMechanisms: PLAIN saslUsername: user saslPassword: file:/path/to/file/password.txt }
password: file:/path/to/file/password.txt
password: env:PASSWORD
password: pass:mypassword