Brief Descriptions

A necessary step for the message broker to allow incoming secure connections is to properly install the SSL certificate files and modify the broker configuration file server.json.

The process described below only works on versions 1.1 and greater due to internal file structure are different and the configuration files are not located in the data partition of the application container.

Generating a Self-Signed Key and Certificate

For some environments, the use of a self-signed certificate is sufficient. For production, the user can obtain certificates and install them on the EFM system.

In the following installation description, we refer to the server key file as key.pemand the server certificate file to be server.pem

On any posix compliant system with an openssl installation, the following command will generate a key file and a corresponding self signed certificate:

openssl req -nodes -x509 -days 365 -newkey rsa:2048 -out server.pem -keyout key.pem -subj "/C=US/ST=CA/L=San Francisco"

Configuring the EFF application to support inbound of HTTPS connections 

There are two ways to modify the EFF application configuration, the first using the Local Manager UI and the second is the ioxclient. The ioxclient allows for automation through scripting if needed.

 

Installing and Configuring Self-Signed Key and Certificate using the Local manager

Connect via a web browser to the IOx router to the defined port for the Cisco IOx Local Manager.

 

For usage of the local manager UI you have to use a browser to connect to the IOx device using the https connection to the port 8443. You have to log into the UI using the required credentials and the

Once logged in, the interface should show the Applications by selecting the Applications tab.

The EFM application is assumed to be installed and running, before we can make changes to the broker configuration file we must first stop the application. Simply select Stop in the Local Manager UI.

After the application has stopped, select the application name “eff” in the tabs.  This will expose additional tabs underneath to allow for more functions. Select the “App-DataDir” tab.

This application directory App-DataDir contains all configuration files and installed links.

First upload the server certificate by selection of the Upload button below the file list. Enter the target path certs/server.pem into the Path edit field of the pop up window. Pay attention not to forget the folder name in the path. Then hit the browse button in the pop up window and select the server certificate file in your local file system. After selecting of the Ok button the Local Manager will create a folder named certs in the application directory and should have put the server certificate server.pem into that folder.

In the next step, we upload the server key file the same way as we uploaded the certificate. Select the upload button a second time and enter certs/key.pem into the target path edit field this time. Then select the Browse button and select the server key file in your local file system. After selection of the Ok button the local manager should have added the key file into the certs, too.

To verify the files have been uploaded, you may check the content of the certs folder by selecting the certs folder in the UI. But don’t forget to get back to the application directory for the next steps. The certs folder should look like in the next screen shot.

We need to modify the existing broker.json configuration file by downloading, editing and replacing the existing file. To download the configuration file broker.json, select it in the file list and store it locally our your computer.

Now modify it with an editor of your choice. Take care the file should still be a plain ASCII file with a valid json contents after editing.  The following green marked elements needed to be modified in the configuration file.

• In the https section, the value of enabled must be set to
• In the https section, add the name of the certificate file “certName”: “server.pem”
• In the https section, add the name of the key file “certKeyName”: “key.pem”

 

After the modification, the configuration file should look like the following (pay attention to maintain the JSON formatting!):

 

{

  "http": {

    "enabled": true,

    "host": "0.0.0.0",

    "port": 8080

  },

  "https": {

    "enabled": true,

    "host": "0.0.0.0",

    "port": 8484,

  "certName": "server.pem",

  "certKeyName": "key.pem"

  },

  "log_level": "info",

  "allowAllLinks": true,

  "maxQueue": 1024,

  "defaultPermission": null,

  "storage": {

    "path": "."

  }

}

To upload the modified configuration file, we first need to delete the original file since the Local Manager does not allow to overwrite an existing file. Therefore we must first select the delete option on the rightside of the broker.json config file to delete the file on the device.

Now you may upload the modified configuration file from your local file system by selecting the Upload button below the file list one more time. Enter broker.json into the Path: field. Then select your modified configuration file by selecting the Browse button. Hit Ok and the modified configuration file should show up in the file list.

Now we start the application by select the Applications main management tab and the Start button for the eff application.

The broker will now start and in addition to TCP port 8080, will now listen port 8484. Port TCP 8080 and 8484 correspond to http and https connections respectively. To verify that the broker is listening, you may check that the configuration is work correctly by downloading the broker log file broker.log from the Logs tab inside the eff management tab. There should now be a second log info line starting the HTTPS server additionally to the HTTP server. 

2017-11-08 10:08:45 INFO [server] - HTTP server bound to 0.0.0.0:8080

2017-11-08 10:08:45 INFO [server] - HTTPS server bound to 0.0.0.0:8484

 

Installing and Configuring Self-Signed Key and Certificate using the ioxclient

The EFM application is assumed to be installed and running, before we can make changes to the broker configuration file we must first stop the application. To stop the application type:

ioxclient application stop eff

In the next step, we upload the server key file the same way as we uploaded the certificate. Select the uploadbutton a second time and enter certs/key.pem into the target path edit field this time.

Start by uploading the server certificate file using the ioxclient command:

ioxclient application appdata upload eff server.pem certs/server.pem

Next, we upload the server key file using:

ioxclient application appdata upload eff key.pem certs/key.pem

We need to modify the existing broker.json configuration file by downloading, editing and replacing the existing file. To download the configuration file broker.json, select it in the file list and store it locally our your computer.

ioxclient applicationappdata view eff broker.json

Now modify it with an editor of your choice. Take care the file should still be a plain ASCII file with a valid json contents after editing.  The following green marked elements needed to be modified in the configuration file.

• In the https section, the value of enabled must be set to
• In the https section, add the name of the certificate file “certName”: “server.pem”
• In the https section, add the name of the key file “certKeyName”: “key.pem”

After the modification, the configuration file should look like the following (pay attention to maintain the JSON formatting!):

{

  "http": {

    "enabled": true,

    "host": "0.0.0.0",

    "port": 8080

  },

  "https": {

    "enabled": true,

    "host": "0.0.0.0",

    "port": 8484,

  "certName": "server.pem",

  "certKeyName": "key.pem"

  },

  "log_level": "info",

  "allowAllLinks": true,

  "maxQueue": 1024,

  "defaultPermission": null,

  "storage": {

    "path": "."

  }

}

To upload the modified configuration file, we first need to delete the original file since the ioxclient does not allow to overwrite an existing file.

ioxclient applicationappdata delete eff broker.json

Now you may upload the modified configuration file from your local file system:

ioxclient applicationappdata upload eff broker.json broker.json

Now we start the application:

ioxclient application start eff

The broker will now start and in addition to TCP port 8080, will now listen port 8484. Port TCP 8080 and 8484 correspond to http and https connections respectively. To verify that the broker is listening, you may check that the configuration is work correctly by downloading the broker log file broker.log from the Logs tab inside the eff management tab. There should now be a second log info line starting the HTTPS server additionally to the HTTP server.

ioxclient application logs download broker.log

 2017-11-08 10:08:45 INFO [server] - HTTP server bound to 0.0.0.0:8080

2017-11-08 10:08:45 INFO [server] - HTTPS server bound to 0.0.0.0:8484 

Remarks

To reach the HTTPS port from outside the device you need to add an appreciate NAT entry into the IOS NAT table.

For this example, assuming address 192.168.101.6 is the outside address:

ip nat inside source static tcp 192.168.101.6 40000 interface Vlan1 8080

ip nat inside source static tcp 192.168.101.6 40001 interface Vlan1 8484