SupportConsoleDevelopersStart a trialContact

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:

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

  1. On the router that establishes the connection, do the following:

    1. Open the /etc/qpid-dispatch/qdrouterd.conf.

    2. 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. 

      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
    ...
}
      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: 

      chmod 0600 /etc/pki/tls/private/tls.key
chown qdrouterd /etc/pki/tls/private/tls.key
      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: 

        password: file:/etc/qpid-dispatch-certs/inter-router/password.txt

      • 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: 

        password: env:CERT_PASSWORD

      • Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: 

        password: pass:mycertpassword

    3. Configure the inter-router connector for this connection to use the sslProfile that you created. 

      connector {
    host: 192.0.2.1
    port: 5001
    role: inter-router
    sslProfile: inter-router-tls
    ...
}
      sslProfile
      The name of the sslProfile that defines the SSL/TLS private keys and certificates for the inter-router network.

  2. On the router that listens for the connection, do the following:

    1. Open the /etc/qpid-dispatch/qdrouterd.conf.
    2. If the router does not contain an sslProfile that defines the private keys and certificates for the inter-router network, then add one.

    3. Configure the inter-router listener for this connection to use SSL/TLS to secure the connection. 

      listener {
    host: 0.0.0.0
    port: 5001
    role: inter-router
    sslProfile: inter_router_tls
    authenticatePeer: yes
    requireSsl: yes
    saslMechanisms: EXTERNAL
    ...
}
      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:

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

  1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  2. 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. 

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

    chmod 0600 /etc/pki/tls/private/tls.key
chown qdrouterd /etc/pki/tls/private/tls.key
    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: 

      password: file:/etc/qpid-dispatch-certs/inter-router/password.txt

    • 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: 

      password: env:CERT_PASSWORD

    • Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: 

      password: pass:mycertpassword

  3. 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. 

    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.

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

Procedure

  1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  2. 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. 

    listener {
    host: 0.0.0.0
    port: 5672
    role: normal
    sslProfile: service-tls
    requireSsl: yes
    authenticatePeer: yes
    saslMechanisms: EXTERNAL
    ...
}
    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

  1. 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): 

    $ sudo saslpasswd2 -c -f qdrouterd.sasldb -u example.com user1
    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).

  2. 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: 

    $ sudo chown qdrouterd /var/lib/qdrouterd/qdrouterd.sasldb

  3. Open the /etc/sasl2/qdrouterd.conf configuration file.

    This example shows a /etc/sasl2/qdrouterd.conf configuration file: 

    pwcheck_method: auxprop
auxprop_plugin: sasldb
sasldb_path: qdrouterd.sasldb
mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
  4. Verify that the mech_list attribute contains the PLAIN mechanism.
  5. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  6. In the router section, specify the path to the SASL configuration file. 

    router {
    mode: interior
    id: Router.A
    saslConfigDir: /etc/sasl2/
}
    saslConfigDir
    The absolute path to the SASL configuration file that contains the path to the SASL database that stores the user names and passwords.

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

    listener {
    host: 0.0.0.0
    port: 5672
    authenticatePeer: yes
    saslMechanisms: PLAIN
    }

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

  1. On the router’s host machine, open the /etc/sasl2/qdrouterd.conf configuration file.

    This example shows a /etc/sasl2/qdrouterd.conf configuration file: 

    pwcheck_method: auxprop
auxprop_plugin: sasldb
sasldb_path: qdrouterd.sasldb
keytab: /etc/krb5.keytab
mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI

  2. Verify the following:

    • The mech_list attribute contains the GSSAPI mechanism.
    • The keytab attribute points to the location of the keytab file.
  3. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  4. In the router section, specify the path to the SASL configuration file. 

    router {
    mode: interior
    id: Router.A
    saslConfigDir: /etc/sasl2/
}
    saslConfigDir
    The absolute path to the SASL configuration file that contains the path to the SASL database.

  5. For each incoming connection using Kerberos for authentication, set the listener to use the GSSAPI mechanism. 

    listener {
    host: 0.0.0.0
    port: 5672
    authenticatePeer: yes
    saslMechanisms: GSSAPI
    }

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:

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

  1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  2. 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. 

    sslProfile {
    name: broker-tls
    caCertFile: /etc/qpid-dispatch-certs/ca.crt
    ...
}
    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.

  3. 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. 

    connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    sslProfile: broker-tls
    ...
}
    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

  1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  2. 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. 

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

    chmod 0600 /etc/pki/tls/private/tls.key
chown qdrouterd /etc/pki/tls/private/tls.key
    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: 

      password: file:/etc/qpid-dispatch-certs/inter-router/password.txt

    • 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: 

      password: env:CERT_PASSWORD

    • Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: 

      password: pass:mycertpassword

  3. Configure the connector for this connection to use the sslProfile that you created. 

    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.

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

  1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

  2. Configure the connector for this connection to provide user name and password credentials to the external AMQP container. 

    connector {
    host: 192.0.2.1
    port: 5672
    role: route-container
    saslMechanisms: PLAIN
    saslUsername: user
    saslPassword: file:/path/to/file/password.txt
    }
    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: 

      password: file:/path/to/file/password.txt

    • 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: 

      password: env:PASSWORD

    • Specify the password in clear text. This option is insecure, so it should only be used if security is not a concern. For example: 

      password: pass:mypassword
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.