This document provides some useful information about Velocity/SNIB3 support for Transport Layer Security (TLS), in the form of Frequently Asked Questions.
...
What is TLS?
TLS is the acronym for Transport Layer Security, which replaced Secure Sockets Layer (SSL).
For some additional information about TLS, see the Wikipedia article about public key certificates.
...
What is required to use TLS in Velocity?
The TLS 1.2 encryption protocol is only supported between a SNIB3 communications expansion board and a Velocity server when all of the following conditions are met:
- The Velocity server is running Velocity 3.7 SP2 or later.
- The SNIB3 is running SNIB3 firmware version 2.05 (or later).
- The SNIB3 is the master communications expansion board on a port (and the downstream controllers must all have a SNIB3).
- The port is configured with a Network Type of either IPv4 or IPv6, and the Protocol of XNET 3:
...
NOTE: Downstream controllers connected using a Serial (RS-485) network cannot use TLS.
...
What must I do to use TLS?
The TLS 1.2 encryption protocol is automatically used when all of the required conditions are met. Otherwise, traditional AES256 encryption is used for the XNET 3 option.
The XNET 2 protocol (which uses AES128 encryption) is still available as an option for the SNIB3.
...
What are the new Velocity events related to TLS?
The following table shows the new Velocity Port events which are related to TLS.
Event ID# | Description | Comment |
|---|---|---|
| 8512 | TLS Configuration complete | TLS trust anchors have been established, and Velocity will automatically re-connect using TLS. |
| 8513 | TLS not supported on this port | This SNIB3's firmware does not support TLS. Upgrade it to version 2.05 (or later). |
| 8514 | Socket connected via TLS | The socket has connected, and a TLS handshake will be initiated to establish a secure communication channel. |
| 8515 | TLS Handshake failed | The TLS handshake failed. There can be several reasons for this and the remedy depends on the condition of failure. (See the troubleshooting question later in this document.) |
| 8517 | SNIB3 failed to authenticate Velocity TLS Certificate | Was this SNIB3 previously connected to a different Velocity server? Try resetting the encryption on both the SNIB3 and the Velocity port. |
NOTE: If there is a problem with the Velocity TLS Certificate, the existing general service alarm 5905 will now report: "Velocity TLS Certificate could not be accessed. TLS support disabled". In this situation, Velocity will fall back to using traditional AES256 encryption for the XNET3 option. However, any SNIB3 previously connected using TLS will need to have its encryption reset, and you will probably also have to reset the Velocity port encryption.
...
How can I tell if TLS is being used?
If TLS is being used, the Port event 8514 (Socket connected via TLS) will appear in Velocity’s Status Viewer when an appropriate port comes online.
...
Do I need to do anything special for TLS when moving my Velocity Server to a different machine?
Moving your Velocity Server to a different machine will require you to import the VelocityTLS certificate from the Velocity database into the new computer’s Windows Certificates store using the import option of the provided GenerateVelocityTLSCertificate.exe tool. (You must also do this when setting up Velocity in a clustered environment.)
To import the VelocityTLS certificate from the Velocity database into the Windows Certificates store:
- Open a command prompt with Administrator privileges (i.e., Run as Administrator).
- Use the cd command to change the directory to the Velocity installation directory.
- Import the VelocityTLS certificate by entering the following command:
GenerateVelocityTLSCertificate –import - Verify that the VelocityTLS certificate was imported to the Local Computer\Personal\Certificates store:
...
...
How can I troubleshoot and fix problems related to TLS?
Problems related to TLS are usually indicated by the generation of a particular event which appears in Velocity’s Status Viewer.
- If you received the Velocity Port event 8513 (TLS not supported on this port), upgrade that SNIB3’s firmware to version 2.05 (or later).
- If you received the Velocity Port event 8515 (TLS Handshake failed), something happened to change the trust anchor configuration on the SNIB3 or in Velocity. For example:
◊ Resetting encryption on one side, either Velocity or SNIB3, but not both
◊ Trying to connect to a SNIB3 that was previously paired with a different Velocity system
◊ Trying to discover a SNIB3 that was previously paired to a different port on the same Velocity system
◊ Switching the protocol of the Velocity port after the TLS connection has been established (so the SNIB3 is listening in TLS mode but Velocity will now try to communicate in a different mode)
◊ Corruption of, manually changing, or deleting the Velocity database that contains TLS-related configuration info
◊ Corruption of the SNIB3’s database storing the trust anchor (highly unlikely)
Check the port’s properties to make sure that the Protocol is set to XNET 3, and the Enable this Port option is checked. You can also try resetting encryption on both the SNIB3 and the Velocity port.
- If you received the Velocity Port event 8517 (SNIB3 failed to authenticate Velocity TLS Certificate), one possible cause is that the SNIB3 was previously connected to a different Velocity server. To solve this problem, reset encryption on both the SNIB3 and the Velocity port.
Another possible cause is that the Velocity server was moved to a different machine. To solve this problem, you must import the VelocityTLS certificate from the Velocity database into the new computer’s Windows Certificates store. The details of that procedure are provided earlier in this document, in the answer to the question about moving a Velocity server to a different machine.
- If you received the Velocity general service alarm 5905 (stating Velocity TLS Certificate could not be accessed. TLS support disabled) TLS communication will be disabled. Therefore any SNIB3 previously connected using TLS will need to have its encryption reset in order to communicate in AES256 mode. You may also have to reset the Velocity port encryption if the AES256 encryption fails.
This is a rare situation that could result from someone manually editing the Velocity database or the Windows certificate store, or applying a Group Policy that locks down access to Velocity’s TLS certificate.
- If Velocity connects to a SNIB3 (as indicated by a socket connected message) but nothing further happens, the most likely cause is that the SNIB3 is configured to communicate in TLS mode but encryption was reset on the Velocity port. To solve this problem, reset encryption on the SNIB3.
Another possible cause is that the SNIB3 is configured to communicate in TLS mode but the Velocity port’s Protocol was changed from XNET 3. To solve this problem: disable the port; change the port’s Protocol back to XNET 3; and re-enable the port.
- If you downgrade the firmware of a SNIB3 which previously was communicating with the Velocity server in TLS mode to an older version (such as 2.04.1038), encryption will be broken and the controller will go offline. To get the controller back online (using traditional AES256 encryption for the XNET 3 protocol), you will have to reset encryption on both the SNIB3 and the Velocity port.