2 . How to use the broker

To run the broker, you can do it by running gradle run in the repository or, if you have downloaded the zip by using gradle distZip, yo can execute the .bat or .sh script that is contained in the bin folder to execute the application. Make sure that the configuration files are included in the folder where the broker is executed.

Configuration

The configuration for the Broker is always a single line with one of the following formats:

file <FILENAME>
or,
<CLASSNAME> <ARGS>

In the first case, the Broker will read the first line of the file <FILENAME> and load it as the configuration. In the second case, <CLASSNAME> shuld be the name of a class that implements the connection.Listener interface, and <ARGS> may be different parameters depending on the class (explained below). If <CLASSNAME> does not specify package, then connection.<CLASSNAME> will be assumed.

For example:

file myConfig.ini
or,
TCPListener -p 5434

By default, the broker will read its configuration from the file 'broker.ini' (located directly in the path where the broker is executed). Alternatively, you may provide the configuration directly as arguments when running the broker:

C:\Broker\bin> broker.bat file myConfig.ini

The API provides to types of connections:

• A simple TCP connection (TCPListener): This connection will be unencrypted, everithing sent will be in plaintext and clients will be recognized by IP address and port.
• A SSL connection (SSLListener): This connection will be encrypted, should provide autenticity, confidenciality and integrity under most configurations. Authentication is achieved via certificates, which will be generated using the keytool application that the jre provides.

Depending on your implementation, you will have to choose which type of connection you need.

TCP connection

To initialize a TCP connection, you have to write a configuration file with this format:

TCPListener -p <PORT>

For example, and by default:

TCPListener -p 5434

SSL connection

Creating the key store

To create a SSL connection, first, we have to create a key store. To do it, we may use keytool that comes with the jre to generate it:

keytool -genkeypair -keystore <PATH TO THE KEY STORE> -keyalg RSA -sigalg SHA256withRSA -storetype JKS -validity <VALIDITY-DAYS>

You will be asked some questions to create it, for example, the password of the key store. This password will be passed to the Broker via configuration.

There are some constraints to how to create the keystore: Most importattly, both the middleware and broker require that the keystore tipe is JKS -storetype JKS (should be the default). On the other hand, the certificate password and the keystore password must be the same (-storepass and -keypass, both of them configured via the -kp switch in SSLListener). Also, note that -keyalg RSA -sigalg SHA256withRSA works with the SSLListener default cipher (TLS_RSA_WITH_AES_128_CBC_SHA256), whereas you may need to change the cipher (-c switch in SSLListener) if you use a different keyalg/sigalg for the certificate (The handshake fails if an incompatible cipher is used).

In order to see how set up the keystores, you might want to look at the AutoKeytool project.

Initializing using the key store.

To initialize the SSL connection using the key store, you will have to write a configuration file with this format:

SSLListener -p <PORT> -t <PATH TO THE TRUSTED KEY STORE> -k <PATH TO THE KEY STORE> -kp <KEY STORE PASSWORD> -pr <PROTOCOL> -c <CIPHER_SUITE>

The <PATH TO THE KEY STORE> points to the keystore where the private key for the Broker to authenticate is. On the other hand, <PATH TO THE TRUSTED KEY STORE> points to the keystore where the trusted client public keys are.

For example, and by default:

SSLListener -p 5434 -t .keystore -k .keystore -kp snowflake -pr TLSv1.2 -c TLS_RSA_WITH_AES_128_CBC_SHA256

Constraints

The broker also features a constraints file, which must be called constraints.ini and located in the path from where the broker is executed. This file must exist, otherwise the broker will refuse to run (although having an empty constraints file is valid).

This configuration file will define constraints that any received MessagePublish must follow. If a received MessagePublish breaks any constraint, the message will be immediately discarded (and thus, not distributed) by the broker.

The constraints.ini configuration will be formatted like so:

[TopicName]
{
    [constraint]=[value]
    [constraint]=[value]
    [...]
}
[TopicName]
{
    [...]
}
[...]

Where [constraint]=[value] might be something like length=5 or something like class=java.lang.String.

length constraints force the data (as a raw byte[]) of the message to be of the specified length. On the other hand, class constraints force the data to be a serialization of an instance of the specified class.

For example:

topic1
{
    length=5
    length=6
}
topic2
{
    class=java.lang.String
}
topic3
{
    class=java.lang.Integer
}
topic4
{
    length=2
}

Multiple constraints can be set to the same topic. Note that in the above example, there cannot be publications to topic1 because it is impossible to follow both constraints.

Rules:

• [constraint]=[value] lines can be indented with spaces or tabs, but other lines ([TopicName], { and }) cannot.
• No empty lines between } and the next [TopicName].