Configuring Secure-Mode in Viakoo Agents
Communication between a Viakoo Communication Agent (ViakooCA) to the Viakoo data center is encrypted using TLS protocols. However, communication between the ViakooCA and the various Viakoo Reader Agents (ViakooRA) within a site at your company defaults to using unencrypted socket communication. For many, this may be okay because communication within your security network is considered trusted in that the network should be isolated with firewalls and/or VLANs, within your organization’s private network. However, if there is a risk that your network could be compromised, it is good to secure this agent-to-agent IP traffic as well.
Release 2020-3 agents now come with the ability to secure the communication between agents. Viakoo Agents can not only encrypt traffic between agents, but also establish a trust relationship such that only one ViakooCA will be recognized by each ViakooRA at a site.
Furthermore, ports 10101 (ViakooCA) and 10106 (ViakooRA) have restricted access. Port 10101, which is the port used to access the ViakooCA console, now defaults to only being accessible from the local host running the ViakooCA (see below to change this setting). 10106 when referenced remotely, only shows the ViakooRA version running on that system and access to the ViakooRA’s console functionality can only be done from the local host running that RA. These extra measures force administrators to have login credentials for the local system before they can configure the Viakoo agents, adding another level of protection.
This document covers the procedures to secure the communication between agents within your network. The sections below explain the steps to do this and the importance of certificates in establishing secure communications:
- Certificates and Secure Communication
- Activating and Deactivating Secure Mode with Self-Signed Certificates
- Creating and Installing CA-Signed Certificates in Agents[optional]
- Updating Agent Certificates[optional]
- Enabling Remote Access for the ViakooCA console[optional]
- Recovering a Broken ViakooCA-ViakooRA Trust Relationship
Certificates and Secure Communication
A foundation of secure communication across networks is the use of public/private asymmetric key pairs. This technology allows an entity, X, to have a public key that people who want to send a private message to X can encrypt the message using X’s public key that can only be decrypted with X’s private key. In the reverse, if X encrypts (or signs) information with its private key, then any entity can verify that the message came from X because it can only be decrypted with X’s public key.
Moreover, to ensure secure communication between a ViakooCA and each ViakooRA within a site, we use a process of SSL Mutual Authentication which works as follows:
- First, each agent is set up with their own private/public key pairs. Once these keys are installed, the ViakooCA can use encrypted traffic to pull data from each ViakooRA.
- Second, in activating secure-mode for an individual ViakooRA, a copy of the ViakooCA’s public key is installed in each ViakooRA.
This not only allows communication between agents to be encrypted, but also, the ViakooCA can then sign its requests so each ViakooRA knows that commands to fetch data, perform upgrades, change password or other operations are all coming from the ViakooCA used to initially activate the site and no other entity.
In these ways, secure-mode prevents anyone from intercepting agent-to-agent communication as well as establishes a trust relationship between each ViakooRA and the site’s associated ViakooCA.
To enable secure communication, ViakooCAs and ViakooRAs have the ability to generate their own unique public key and private key pair. The private key is stored securely on the respective system’s keystore. In basic secure-mode, each agent is able to generate a self-signed certificate containing the associated agent’s public key which then can be used to initiate encrypted communication with the agent.
To increase security, it is possible to have the public keys signed by a trusted Certificate Authority (CA). These signed public keys, or certificates allow users, networks and browsers to know the communication is coming from a trusted entity. Generating such a certificate involves asking each agent for a special form of the public key called, a Certificate Signing Request (CSR). This CSR can be used to request a certificate for the associated agent that can be “signed” by trusted third-parties (CAs). The resulting certificates can then be installed into the associated agent and are verified using the public key of the associated CA.
Signed Certificate Expiration
The extra work associated with generating CA-signed certificates for your agents is compounded because certificates issued this way have a built-in expiration date. Therefore, you will need to remember to renew these certificates on a periodic basis ahead of their expiration dates to make sure you maintain trusted communication.
This can be done somewhat automatically for customers of Viakoo’s Device Certificate Manager. However, customers without this option will have to manually reissue new certificates and install them for each agent before the current certificate expires.
Using CA-signed certificates can add some complexity to your setup and becomes much simpler if you purchase and use Viakoo Device Certificate Management (Viakoo DCM) which can automate much of this work. Talk to your Viakoo sales representative for information about adding Viakoo DCM to your configuration if you haven’t already done so.
If you want to install and manage agent certificates without Viakoo DCM, instructions to do so are in the section Creating and Installing Agent Certificates below.
Activating and Deactivating Secure Mode with Self-Signed Certificates
To activate encrypted communication between Viakoo Agents, go to the administrative menu of the ViakooCA’s console (port 10101 for the associated server) and select “Configure Secure Mode.”
NOTE: Access to the ViakooCA console through port 10101 or 10161 are restricted to the system hosting the ViakooCA. This forces the extra security step of having to have login access to this system. Refer to the section Enabling Remote Access to undo this restriction.
This will bring up the “Secure Mode Configuration” Page which has controls to activate secure-mode for both the ViakooCA and ViakooRAs.
This section takes you through the process to securing a site using self-signed certificates. The steps are as follows:
- Secure the ViakooCA console by forcing it to only be available through https and only accessible from the system running the ViakooCA itself.
- Secure traffic to each ViakooRA.
Note: steps can be done in either order with self-signed certificates but it is recommended to do the ViakooCA first.
Activating Secure Mode for the ViakooCA
Secure Mode for the ViakooCA means communication with the ViakooCA console is done using HTTPS, disabling access to HTTP. This encrypts traffic to the ViakooCA console. By default, it also blocks access to the ViakooCA console from any system with the exception of the host running the ViakooCA itself. You can change this setting in the “Advanced” tab (see below).
To Activate “Secure-Mode” in the ViakooCA, simply click on the “Activate” button for the Viakoo Communication Agent (ViakooCA) subtab. If you are on the same system as the ViakooCA, then you will be redirected to the secure-socket interface of the ViakooCA. This secure interface to ViakooCA console uses port 10141 instead of 10101 (i.e., “https://<localhost IP>:10141”). Because it is using a self-signed certificate, you will have to explicitly trust this connection in your browser before it will take you back to the ViakooCA console.
To reverse the process, click the “Deactivate” button.
Activating Secure Mode for Each ViakooRA
Now that you’ve activated secure mode in the Viakoo CA, you need to activate Secure-Mode for each ViakooRA in your site’s configuration. To do this in the “Configuring Secure-Mode” page, click on the “Reader Agents” subtab.
NOTE: you must use a real IP address in referencing the ViakooRA on same system as the ViakooCA. Specifically, if you have originally activated this ViakooRA with “localhost” or “127.0.0.1” (reference to local system), you will need to change this ViakooRA’s IP address to the IP address of this system before activating secure-mode on this ViakooRA. If you activate secure-mode with the ViakooRA set to “localhost” or 127.0.0.1, activating will fail yet local ViakooRA may be in secure-mode, creating a broken trust relationship with the ViakooCA. Refer to the section on “Recovering Broken ViakooCA-ViakooRA Trust Relationship” below.
Just like with the ViakooCA, you only need to click the “Activate” button for each Reader Agent. Activating secure-mode for a Reader Agent not only converts it to only accepting traffic through HTTPS, in the process, it receives the associated ViakooCA’s public key.
When the agents are in secure-mode, you will see the padlock icon in the “Locked” position.
Just as with the ViakooCA, you can simply click “Deactivate” to exit secure-mode between the ViakooCA and this ViakooRA.
NOTE: Because the ViakooRA is now in a trust relationship with the ViakooCA that activated it, changing the ViakooCA’s keys or certificate at this point will break this trust relationship. Reinstalling the ViakooCA or installing a certificate in the ViakooCA at this point, effectively breaks the trust relationship with all secure-mode-activated ViakooRAs. If you need to reinstall the ViakooCA or want to install a certificate for the ViakooCA (see below), you must, from the ViakooCA console, first deactivate secure-mode in each associated ViakooRAs.
Creating and Installing CA-Signed Certificates in Agents
Certificates that are signed by a trusted Certificate Authority add an additional layer of security by forming a 3rd-party trust verification in secure communication. This allows browsers and other tools to trust the agents as part of creating encrypted traffic.
Steps for Generating Certificates for Each Agent
This section describes how you can generate certificates for the agents using your chosen certificate authority. Using certificates signed by a certificate authority is optional. Activating without certificates installed causes the agents to automatically use self-signed certificates.
Steps to be done manually by activating technician or administrator:
- Create and install certificates for each ViakooRA
- Generate CSR for each ViakooRA
- Use each ViakooRA CSR to create certificate for each ViakooRA
- Install new certificate in each ViakooRA
- Create and install certificate for the ViakooCA
- Generate CSR for the ViakoooCA
- Create Certificate for the ViakooCA
- Install Certificate for ViakooCA
- Activate Secure-Mode in the ViakooCA
- Activate Secure-Mode in each ViakooRA
Generating and Installing ViakooRA Certificates
NOTE: To generate CSRs and install certificates, each affected ViakooRA and the associated ViakooCA at the site must have Secure-Mode Deactivated.
To generate the CSR for each RA, you need to navigate your browser to the ViakooRA’s console (http://localhost:10106).
You then need to click on the “Manage Secure Mode” link to get to the page to configure secure-mode settings.
Verify Subject Name
A key component of the CSR and the eventual certificates generated from it will be the Subject Name. This name will be embedded in the CSR generated in the next step and must match how the ViakooRA will be referenced by the ViakooCA. If these values don’t match, communication with this ViakooRA will not work when in secure-mode with the associated certificate gets installed.
To verify the Subject Name of the ViakooRA is set to the correct value, look on the listed Subject Name on the RA's "Manage Secure Mode" page.
If the Subject Name is not the correct reference for this RA, click "Edit" to change.
By default, this list will be the available IP addresses associated with this machine. It will very likely default to the one the ViakooCA has already used to reference this ViakooRA but it is important to verify it is set to the correct one.
Generate the ViakooRA’s CSR
After verifying the Subject Name for this ViakooRA, the next step is to generate a CSR. From the “Manage Secure-Mode” screen, click “Download CSR” to generate a CSR for this ViakooRA and have it downloaded to your “Downloads” folder.
It will have a name in the following format:
“ViakooRA-<subj name><current date>.csr”
Use this file to submit a certificate request of your certificate authority. Make sure to have the new certificate be generated in PEM format.
Install the Certificate
Download the PEM certificate file to this system. Then, from the “Manage Secure Mode” screen, click “Choose File” to select this certificate file.
At this point, the certificate is loaded and will be used when you activate secure-mode from the ViakooCA console below.
Repeat this process for each ViakooRA at the site.
NOTE: Only the certificate generated from the CSR associated with this same ViakooRA can be installed into this ViakooRA. Installing a certificate for some other agent or device will fail when you click “Install.”
Generating Certificate for the ViakooCA
NOTE: To install new certificates in the ViakooCA, the ViakooCA and ViakooRAs at the site must have Secure-Mode Deactivated.
As with ViakooRA’s, generating a certificate for and installing them requires the following steps:
- Verify the Subject Name
- Generate the CSR for the ViakooCA
- Generate the Certificate file
- Install Certificate
Verifying Subject Name
To verify the Subject Name, click on the “Advanced” subtab to see the current value for the CA’s Subject Name.
If that is not your desired Subject Name, you can use the pull-down selector to choose from the available alternatives.
Once chosen, click on the “Communication Agent” subtab to perform the next step.
Generate a CSR for the ViakooCA
From the Communications Agent subtab, with the Subject Name the way you want it, click “Generate CSR."
In the “Communication Agent” tab, generate a CSR by clicking on the “Generate” link under “Generate CSR”. The agent will generate a CSR and download it to your systems download folder with a name in the following format:
ViakooCA-<ip address/subject name>-<date>.csr
For example, if your system’s IP address (subject name) is 10.102.199.149, and you create the CSR on July 23rd, 2020, the file will have the name:
This CSR file can then be used with your certificate authority to generate a signed certificate. Have the certificate file generated in Privacy Enhanced Mail (PEM) format.
Then from the Configure Secure Mode->Communications Agent screen, under the “Install Certificate heading, click “Choose File”.
Then navigate to, and select the file in the file chooser.
And finally, click “Install.”
When the ViakooCA activates secure mode, this certificate will be the one it uses to enable secure communication.
Activating Secure Mode with Certificates
Once all the agents have installed certificates, activating secure mode for the ViakooCA and all associated ViakooRAs will use the installed certificates instead of self-signed certificates add a greater level of security to your communication.
Updating Agent Certificates
There are three scenarios that will require you to update certificates on agents:
- Starting with self-signed certificates, you want to upgrade the agents to fully signed certificates.
- Certificates that were issued are now expiring.
- Certificates have been revoked
Updating Certificates in a ViakooRA
To update a certificate in a ViakooRA, perform the following steps:
- Generate new CSR or Reuse original CSR for the associated ViakooRA.
- Request a new certificate from your Certificate Authority (CA). Save the certificate in PEM format.
- Deactivate secure-mode for the associated RA.
- Install the certificate from the ViakooRA’s “Secure Mode” console as before.
- Reactivate secure-mode for the associated RA.
Note: the associated ViakooRA may need a restart to fully install the new certificate.
Updating Certificates in a ViakooCA
Steps to update ViakooCA Certificate:
- Generate or Reuse CSR for the ViakooCA
- Request a certificate from your Certificate Authority (CA). Save the certificate in PEM format.
- Deactivate secure-mode on ALL ViakooRAs.
- Install ViakooCA’s certificate
- Reactivate secure-mode on ALL ViakooRAs.
Because the ViakooCA’s certificate must be installed in the ViakooRA’s trust store to enable SSL Mutual Authentication, if the ViakooCA’s installed certificate changes without updating the certificate in each ViakooRA’s trust store, communication will stop between agents.
Therefore, it is imperative that you disable secure-mode for ALL ViakooRA’s before updating the ViakooCA’s certificate. If you forget this step and find your agents stuck go to section on “Recovering ViakooRA’s”
If you make a mistake and install a new certificate in the ViakooCA without deactivating secure-mode with ALL ViakooRAs, follow the procedures above in Recovering a Broken ViakooCA-ViakooRA Trust Relationship.
Enabling Remote Access to the ViakooCA
As mentioned above, activating secure-mode in the ViakooCA disables connections from external systems to the one hosting the ViakooCA. This forces administrators to have login credentials to the system running the ViakooCA.
If you are on a remote system from the ViakooCA, your connection will be severed as soon as you activate secure-mode. If you want to enable usage of the ViakooCA console at this site, login to the server hosting the site and bring up the ViakooCA Console and go to “Configure Secure Mode”, then click “Advanced”.
Now click “Remote” to reveal the “Remote Access” checkbox. Clicking on the checkbox allows users to reach this ViakooCA’s console from any system that can reach it from the network. Unchecking this checkbox forces users to login to the ViakooCA’s host system to then get access to the console.
Recovering a Broken ViakooCA-ViakooRA Trust Relationship
The following situations can break this trust relationship:
- The system hosting the ViakooCA crashes and you need to reactivate the site using a ViakooCA hosted on a different system.
- You reinstall the ViakooCA without preserving and restoring the current configuration settings.
- Installing a new ViakooCA certificate without first “deactivating” secure mode for each associated ViakooRA.
In all cases, the ViakooRAs don’t have the correct public key for the ViakooCA and as a result, will not accept “deactivate” secure-mode commands from the new ViakooCA. In these cases, you must deactivate secure mode from the ViakooRA’s console from the system hosting that ViakooRA.
To do this, login to the associated system hosting the ViakooRA in question. From a browser window, navigate to the ViakooRA’s console:
https://<local system’s IP address>:10146
This will take you to the local ViakooRA’s console.
Click on the “Manage Secure Mode” to get to the Secure-Mode screen. When secure-mode is active, it will look like this:
Click on “Advanced” settings. This will take you to a page with only two options:
- Reset SSL
- Deactivate SSL
If-and-only-if the trust relationship between the ViakooRA and its ViakooCA has been lost, you can recover the ViakooRA by clicking “Deactivate SSL” on this screen. At this point, the new ViakooCA should be able to talk to this ViakooRA, including the ability to reactivate secure-mode with this ViakooRA.
Repeat this process with any remaining ViakooRAs that have lost their trust relationship with the ViakooCA.
NOTE: if the ViakooCA still believes that a ViakooRA is in secure-mode when it has been deactivated from the ViakooRA console, you will need to remove this RA and then re-add it in the ViakooCA console.