Chapter 6. Security

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 and payload encryption

6.1. Setting Up SSL/TLS for Encryption and Authentication

Before you can secure incoming and outgoing connections using SSL/TLS encryption and authentication, you must first set up the SSL/TLS profile in the router’s configuration file.

Prerequisites

You must have the following files in PEM format:

  • An X.509 CA certificate (used for signing the router certificate for the SSL/TLS server authentication feature).
  • A private key (with or without password protection) for the router.
  • An X.509 router certificate signed by the X.509 CA certificate.

Procedure

  • In the router’s configuration file, add an sslProfile section: 

    sslProfile {
    name: NAME
    certDb: PATH.pem
    certFile: PATH.pem
    keyFile: PATH.pem
    password: PASSWORD/PATH_TO_PASSWORD_FILE
    ...
}
    name

    A name for the SSL/TLS profile. You can use this name to refer to the profile from the incoming and outgoing connections.

    For example: 

    name: router-ssl-profile
    certDb

    The absolute path to the database that contains the public certificates of trusted certificate authorities (CA).

    For example: 

    certDb: /qdrouterd/ssl_certs/ca-cert.pem
    certFile

    The absolute path to the file containing the PEM-formatted public certificate to be used on the local end of any connections using this profile.

    For example: 

    certFile: /qdrouterd/ssl_certs/router-cert-pwd.pem
    keyFile

    The absolute path to the file containing the PEM-formatted private key for the above certificate.

    For example: 

    keyFile: /qdrouterd/ssl_certs/router-key-pwd.pem
    passwordFile or password

    If the private key is password-protected, you must provide the password by either specifying the absolute path to a file containing the password that unlocks the certificate key, or entering the password directly in the configuration file.

    For example: 

    password: routerKeyPassword

    For information about additional sslProfile attributes, see sslProfile in the Configuration Reference.

6.2. Setting Up SASL for Authentication and Payload Encryption

If you plan to use SASL to authenticate connections, you must first add the SASL attributes to the router entity in the router’s configuration file. These attributes define a set of SASL parameters that can be used by the router’s incoming and outgoing connections.

Prerequisites

Before you can set up SASL, you must have the following:

Procedure

  • In the router’s configuration file, add the following attributes to the router section: 

    router {
    ...
    saslConfigPath: PATH
    saslConfigName: FILE_NAME
}
    saslConfigPath

    The absolute path to the SASL configuration file.

    For example: 

    saslConfigPath: /qdrouterd/security
    saslConfigName

    The name of the SASL configuration file. This name should not include the .conf file extension.

    For example: 

    saslConfigName: qdrouterd_sasl

6.3. Securing Incoming Connections

You can secure incoming connections by configuring each connection’s listener entity for encryption, authentication, or both.

Prerequisites

Before securing incoming connections, the security protocols you plan to use should be set up.

Choices

6.3.1. Adding SSL/TLS Encryption to an Incoming Connection

You can configure an incoming connection to accept encrypted connections only. By adding SSL/TLS encryption, to connect to this router, a remote peer must first start an SSL/TLS handshake with the router and be able to validate the server certificate received by the router during the handshake.

Procedure

  • In the router’s configuration file, add the following attributes to the connection’s listener entity: 

    listener {
    ...
    sslProfile: SSL_PROFILE_NAME
    requireSsl: yes
}
    sslProfile
    The name of the SSL/TLS profile you set up.
    requireSsl
    Enter yes to require all clients connecting to the router on this connection to use encryption.

6.3.2. Adding SASL Authentication to an Incoming Connection

You can configure an incoming connection to authenticate the client using SASL. You can use SASL authentication with or without SSL/TLS encryption.

Procedure

  • In the router’s configuration file, add the following attributes to the connection’s listener section: 

    listener {
    ...
    authenticatePeer: yes
    saslMechanisms: MECHANISMS
}
    authenticatePeer
    Set this attribute to yes to require the router to authenticate the identity of a remote peer before it can use this incoming connection.
    saslMechanisms

    The SASL authentication mechanism (or mechanisms) to use for peer authentication. You can choose any of the Cyrus SASL authentication mechanisms except for ANONYMOUS. To specify multiple authentication mechanisms, separate each mechanism with a space.

    For a full list of supported Cyrus SASL authentication mechanisms, see Authentication Mechanisms.

6.3.3. Adding SSL/TLS Client Authentication to an Incoming Connection

You can configure an incoming connection to authenticate the client using SSL/TLS.

The base SSL/TLS configuration provides content encryption and server authentication, which means that remote peers can verify the router’s identity, but the router cannot verify a peer’s identity.

However, you can require an incoming connection to use SSL/TLS client authentication, which means that remote peers must provide an additional certificate to the router during the SSL/TLS handshake. By using this certificate, the router can verify the client’s identity without using a username and password.

You can use SSL/TLS client authentication with or without SASL authentication.

Procedure

  • In the router’s configuration, file, add the following attribute to the connection’s listener entity: 

    listener {
    ...
    authenticatePeer: yes
}
    authenticatePeer
    Set this attribute to yes to require the router to authenticate the identity of a remote peer before it can use this incoming connection.

6.3.4. Adding SASL Payload Encryption to an Incoming Connection

If you do not use SSL/TLS, you can still encrypt the incoming connection by using SASL payload encryption.

Procedure

  • In the router’s configuration file, add the following attributes to the connection’s listener section: 

    listener {
    ...
    requireEncryption: yes
    saslMechanisms: MECHANISMS
}
    requireEncryption
    Set this attribute to yes to require the router to use SASL payload encryption for the connection.
    saslMechanisms

    The SASL mechanism to use. You can choose any of the Cyrus SASL authentication mechanisms. To specify multiple authentication mechanisms, separate each mechanism with a space.

    For a full list of supported Cyrus SASL authentication mechanisms, see Authentication Mechanisms.

6.4. Securing Outgoing Connections

You can secure outgoing connections by configuring each connection’s connector entity for encryption, authentication, or both.

Prerequisites

Before securing outgoing connections, the security protocols you plan to use should be set up.

Choices

6.4.1. Adding SSL/TLS Client Authentication to an Outgoing Connection

If an outgoing connection connects to an external client configured with mutual authentication, you should ensure that the outgoing connection is configured to provide the external client with a valid security certificate during the SSL/TLS handshake.

You can use SSL/TLS client authentication with or without SASL authentication.

Procedure

  • In the router’s configuration file, add the sslProfile attribute to the connection’s connector entity: 

    connector {
    ...
    sslProfile: SSL_PROFILE_NAME
}
    sslProfile
    The name of the SSL/TLS profile you set up.

6.4.2. Adding SASL Authentication to an Outgoing Connection

You can configure an outgoing connection to provide authentication credentials to the external container. You can use SASL authentication with or without SSL/TLS encryption.

Procedure

  • In the router’s configuration file, add the saslMechanisms attribute to the connection’s connector entity: 

    connector {
    ...
    saslMechanisms: MECHANISMS
    saslUsername: USERNAME
    saslPassword: PASSWORD
}
    saslMechanisms

    One or more SASL mechanisms to use to authenticate the router to the external container. You can choose any of the Cyrus SASL authentication mechanisms. To specify multiple authentication mechanisms, separate each mechanism with a space.

    For a full list of supported Cyrus SASL authentication mechanisms, see Authentication Mechanisms.

    saslUsername
    If any of the SASL mechanisms uses username/password authentication, then provide the username to connect to the external container.
    saslPassword
    If any of the SASL mechanisms uses username/password authentication, then provide the password to connect to the external container.