Contents

This section covers the following topics:

TCP with JSSE Security

  1. Launch the Fiorano Studio for offline configuration of the FioranoMQ server.
  2. Select Tools > ConfigureProfile from the menu bar, and open the profile needed. Navigate to %selectedProfile% > Fiorano > SocketAcceptors > Port-1 > ConnectionManager in the ServerExplorer.
  3. Change the Protocol property to SUN_SSL.



  4. Change the UseSystemPropsForSSL to true (Optional)

    Icon

    The public/private keys and/or certificates used by the FioranoMQ Server can be loaded by specifying the related system properties, or by installing the appropriate security managers which can load the certificates. Please see the note at the start of Section 4.5.1.

  5. Navigate to %selectedProfile% > Fiorano > etc > FMQConfigLoader. Right-click on FMQConfigLoader, and select Add Attribute from the pop-up menu. Add an additional attribute with the name SSLEnabled and with a value that is 'true'.



  6. Navigate to %selectedProfile% > Fiorano > socketAcceptors > port-1 > ConnectionManager. Check the default value of property ManagerClassName. Ensure that the default value of ManagerClassName is fiorano.jms.ex.sm.def.DefaultJSSESecurityManager. (Optional)

    Icon

    This parameter is deprecated. Alternatively, in order to load the KeyStore and TrustStore, for initializing the context in which SSL Sockets are created, corresponding system properties should be set, and UseSystemPropsForSSL should be set to true.



  7. Navigate to Fiorano > jmx > connector > JMSBasedJMXConnector2, and set the following properties to allow the JMSConnector to connect to the secure server.
    1. SecurityProtocol: SUN_SSL
    2. Protocol: TCP
    3. SecurityManagerClass: fiorano.jmx.connector.fmq.security.JSSESecurityManager
       


  8. Right-click the FioranoMQ domain in the Profile Manager, and select the Save option from the pop-up menu.

    Icon

    Changes get saved in the Configs.xml file.

     


  9. Clear the existing database using script ClearDB.bat located in %FIORANO_HOME%\fmq\bin directory.

  10. Start the Server again using script file fmq.bat located in %FIORANO_HOME%\fmq\bin directory.


    The server starts accepting connections on TCP in the SSL (JSSE) mode.

HTTPwithJSSESecurity

  1. Launch the Fiorano Studio for offline configuration of the FioranoMQ server.
  2. Select Tools > Configure Profile from the menu bar, and open the profile needed. Navigate to %selectedProfile% > Fiorano > SocketAcceptors > Port-1 > ConnectionManager.
  3. Change the protocol property from TCP to HTTPS_SUN.
  4. Navigate to %selectedProfile% > Fiorano > etc > FMQConfigLoader. Right-click on FMQConfigLoader and select Add Attribute from the pop-up menu. Add an additional attribute with the name SSLEnabled and with the value 'true'.
  5. Navigate to %selectedProfile% > Fiorano > socketAcceptors > port-1 > ConnectionManager. Check the default value of property ManagerClassName. Ensure that the default value of Security manager is fiorano.jms.ex.sm.def.DefaultJSSESecurityManager.
  6. Navigate to Fiorano > jmx > connector > JMSBasedJMXConnector2, and set the following properties to allow JMSConnector to connect to the secure server.
    1. Protocol: HTTP
    2. SecurityManagerClass: fiorano.jmx.connector.fmq.security.JSSESecurityManager
    3. SecurityProtocol: SUN_SSL
  7. Right-click the FioranoMQ domain in the Server Explorer, and select the Save option from the pop-up menu. Changes are saved in the Configs.xml file.
  8. Clear the existing database, using script ClearDB.bat, located in the %FIORANO_HOME%\fmq\bin directory.

9. Start the Server again, using script file fmq.bat, located in %FIORANO_HOME%\fmq\bin directory.

The server starts accepting connections on HTTPS in the SSL (JSSE) mode.

Note:

  1. A similar procedure is followed to enable SSL for FES/FPS servers. For FPS profiles, the Protocol, SecurityProtocol and SecurityManagerClass properties for Fiorano > jmx > Engine > ClientJMXEngine also need to be changed.
  2. When FioranoMQ server is running with HTTPS_SUN protocol, pinging is enabled at the server. Also, the client connecting to the server must enable ping.

4.5.1 Starting FMQ Server in SSL Mode

The setup of the basic configurations for the FioranoMQ server consists of changing the default TCP protocol to 'SUN_SSL' in the connection manager properties and turning on the SSL flag in the FMQConfigLoader.

In order to use system properties to specify the KeyStore, TrustStore and the corresponding password, which is used to load and initialize the "context" in which the SSL-enabled Server Socket is created, enable theUseSystemPropsForSSL parameter in the Connection Manager configuration by following the similar steps taken to configure Port Number in Section 4.1. If this parameter is enabled, then the following system properties should be set before starting the FioranoMQ Server:

  • javax.net.ssl.keyStore
  • javax.net.ssl.keyStorePassword
  • javax.net.ssl.keyStoreType (Optional; if not set, JDK default will be used)
  • javax.net.ssl.trustStore
  • javax.net.ssl.trustStorePassword
  • javax.net.ssl.trustStoreType (Optional; if not set, JDK default will be used)
  • javax.net.debug (Optional; if not set, JDK default will be used)

These system properties should be specified in the file - "%INSTALLER_HOME%/fmq/bin/fmq.conf" - under the section <java.system.props>

Alternatively, if UseSystemPropsForSSL is not enabled, by default, the FMQ server uses 'DefaultJSSEKeys', the Java keystore file, for authenticating the client connections. This keyStore is loaded in the Client or Server process, using the Security Managers installed for client and server respectively. Other certificate files can be ignored as they are not in use. To check which certificates are in a Java keystore, the 'keytool' utility which comes along with the JDK installed is used. To check which certificates are stored in the Java keystore 'DefaultJSSEKeys' file, the following command can be used:

Note: 'keytool' can be found at %JAVA_HOME%\bin\keytool

4.5.2 Generating 'Keystores' of 'type' JKS, provided by SUN

Java Keytool is a key and certificate management utility. It allows users to manage their own public/private key pairs and certificates and also allows users to cache the latter. Java Keytool stores the keys and certificates in a 'keystore'.
The following command can be used to create a 'keystore':
keytool -genkey -alias sampleKS -keyalg RSA -keystore C:\keystore
Where,

  •  -genkey - is used to generate a key pair (a public key and associated private key). This wraps the public key into an X.509 v1 self-signed certificate that is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry, identified by an alias.
  • -alias - is the unique alias for accessing keystore entries (key and trusted certificate entries). Typically, the company name or hostname of the Server forms the alias.
  • -keyalg - specifies the algorithm to be used to create the key pair.
  • -keystore - is used for specifying the name and location of the persistent keystore file for keystore that is managed by the keytool.

Note: keytool –help to reveal other options of keytool.

After executing the above command for creating the certificate, information related to the creation of the certificate needs to be provided as shown below.

Enter keystore password: passwd

Enter key password for <sampleKS>

(RETURN if same as keystore password):

This keystore acts as a self-signed certificate. A certificate request can be generated in the event that it needs to be signed by Certification Authorities such as Verisign or eTrust.

4.5.3 Server Side Configurations

The Security Manager loads the certificates/keys from the Keystore that has been created. Please note that this section describes the procedure to create and install the Server security manager only when UseSystemPropsForSSL is disabled. In case this property is enabled, this section can be skipped, and the KeyStore and TrustStore location and related properties can be provided directly as system properties for the FioranoMQ Server. Security manager class should implement fiorano.jms.ex.sm.IExSecurityManager.

The server, by default, uses fiorano.jms.ex.sm.def.DefaultJSSESecurityManager class as a Security Manager. This value can be modified from the Studio using Profile Manger at:

Profiles > FioranoMQ > socketAcceptors > port-1 > ConnectionManager[properties] > ManagerClassName

A sample Security Manager Class is displayed below.

JSSESecurityManager.java




4.5.3.1 Compiling the Security Manager

  1. The compile-client.sh script present in %Fiorano_Home%\fmq\bin folder is used to compile the Security Manager class.
  2. Add the following line to compile-client.conf (located at the same place as .sh/.bat) file [Under <java.classpath> properties] prior to compilation:

3. Compile the Security Manager:

4.5.3.2 Adding the Security Manager class to the Server's classpath

After compiling the Security Manager class, please add the path under java.classpath [in the fmq.conf (located at %Fiorano_Home%\fmq\bin) file, the class path is specified as:

The folder containing the security manager class can be added to this list, or the security manager class can be copied to one of the folders listed.

EnforceClientAuthentication. (Refer to the profile screenshot below.) If the EnforceJSSEAuthentication parameter is enabled in ConnectionManagerConfigurations, then the server validates the certificates provided by the client.

To enable this, the keystore created should be added to the trusted Stores.

The fmq.conf file is used here. By default the value is:

javax.net.ssl.trustStore=../profiles/FioranoMQ/certs/jssecacerts. This can be changed to the keystore created:

javax.net.ssl.trustStore=<path - is the path to the keystore>

4.5.4 Client Side Configuration

In order to provide transport layer security on operations involved between the Clients and the FioranoMQ server, the SECURITY_PROTOCOL must be enabled. This can be done by setting the environment variable using the parameter Context.SECURITY_PROTOCOL to FioranoJNDIContextConstants.PROTOCOL_JSSE_SSL
or
MetaDataConstants.PROTOCOL_JSSE_SSL
before creating InitialContext. For example:
env.put(Context.SECURITY_PROTOCOL, FioranoJNDIContextConstants.PROTOCOL_JSSE_SSL);
(or)
env.put(Context.SECURITY_PROTOCOL, MetaDataConstants.PROTOCOL_JSSE_SSL);
Whenever this variable is set, FMQ's Client library tries to load the Public/Private keys/certificates. This can be done in two different ways. One way is to set the System property USE_SYSTEM_PROPERTIES_FOR_SSL_TLS
This provides the system properties for specifying KeyStore and TrustStore locations like:

  • javax.net.ssl.keyStore
  • javax.net.ssl.keyStorePassword
  • javax.net.ssl.keyStoreType (Optional - if not set JDK default will be used)
  • javax.net.ssl.trustStore
  • javax.net.ssl.trustStorePassword
  • javax.net.ssl.trustStoreType (Optional - if not set JDK default will be used)
  • javax.net.debug (Optional - if not set JDK default will be used)


Alternatively, an installed Client Security Manager can be used to load the required certificates into Client process (described later in this section). In this case, The Security Manager loads the certificates/keys from the Keystore that has been created, and the Security manager class should implement fiorano.jms.runtime.IFMQSecurityManager. FMQ Client Libraries search for the environment variable set by using FioranoJNDIContextConstants.SSL_SECURITY_MANAGER, which stores the fully qualified class name of the SecurityManager that implements this interface. For example:

env.put(FioranoJNDIContextConstants.SSL_SECURITY_MANAGER, "com.xxx.yyy.zzz.SomeSecurityManagerImpl");

Please check the Java docs for the class fiorano.jms.runtime.IFMQSecurityManager for more information on this API that needs to be implemented.

Certain samples are provided in the fmq/samples/SSLSamples directory for reference on how the class implementing fiorano.jms.runtime.IFMQSecurityManager can be used while performing SSL enabled communication with the FioranoMQ Server. Those samples by default use JSSESecurityManager class (also provided along with the samples) as a Security Manager. The fully qualified class name is passed as an environment variable

FioranoJNDIContext.SSL_SECURITY_MANAGER

while creating the InitialContext from the client. A sample Security Manager Class is shown below for your convenience.

JSSESecurityManager.java

4.5.4.1 Compiling the Security Manager

  1. compile-client.sh script present in %Fiorano_Home%\fmq\bin folder is used to compile the Security Manager class.
  2. The following line should be added to compile-client.conf (located at the same place as .sh/.bat) file [Under <java.classpath> properties] before compiling.

3. Compile the Security Manager by, $> compile-client.sh JSSESecurityManager.java

4.5.4.2 Adding the Security Manager class to the Client's classpath

After compiling the Security Manager class, please add the path under java.classpath. In run-client.conf (this file is also located at %Fiorano_Home%\fmq\bin) file, the class path is specified as following

The folder or jar that contains security manager class can be added to this list.
Important - From FioranoMQ 9.3.0 release onwards, the classes which are used for initializing Key and Trust managers while loading the keys from the KeyStore have been changed from com.sun.net.ssl.* package to javax.net.ssl.* package. This is as per the changes involved in the Sun's JDK 5 as the APIs provided in com.sun.net.ssl.* package have been deprecated. Henceforth, FioranoMQ only supports the usage of javax.net.ssl.* package's classes. These classes include:

4.5.5 Creating Certificates for OpenSSL in C++

.pem format or converting the above generated keystore to PEM encoding

Portcele is a java tool with an UI for managing the Java certificates. It can be downloaded at http://sourceforge.net/projects/portecle/. This tool is used to convert java certificates into other compatible formats.

To start this tool, type in the command,


  1. Open the keystore that needs to be converted to the .PEM format using Portcele. All the information related to the certificate can be viewed here.
  2. Navigate to File >> OpenKeyStoreFile. Choose the keystore that was created.
  3. Enter the password provided at the time of the creation of the keystore.


4. Right-click on certificate, and choose export. Select the export 'type' as "Private Key and Certificates", and the export format as "PEM Encoding".

5. Enter the password that was used to create the keystore using the java keytool after clicking 'OK'.

6. Save the file as clientCert.pem or any other name.

This file is used by the C++ RTL for SSL communication.

The client side configurations in C++ lies within the environment variables used in creating the initial context as shown below:

In the code above, certfile and keyfile refer to the location of the clientCert.pem created using portcele.

By default, the C++ samples use the 'dsa-client-cert.pem' for the certificate and 'enc-dsa-client-key.pem' for the private key.

'passwd', is the password that is used when creating the certificate.

Default certificates are located at %Fiorano_Home%\fmq\clients\c\native\certs.

Adaptavist ThemeBuilder EngineAtlassian Confluence