This week, we're releasing a new version of VirtualHub v2 that introduces the concept of security mode. As the name suggests, security modes let you configure VirtualHub network access parameters to suit your needs.
When we added SSL/TLS support to VirtualHub, we quickly realized that in some situations, certificate management could become a pain. What's more, the default behavior of encrypting communications without setting a password didn't make much sense. We therefore decided to add a new attribute to the YNetwork class, allowing you to choose the VirtualHub operating mode.
The first time you connect, VirtualHub asks you to select the security mode to be used. The different modes are legacy, mixed, and secure. We've also left an undefined option, if you're in a hurry and want to configure this attribute later. This undefined mode is identical to legacy mode, but it displays this window every time you connect.
When you connect for the first time, VirtualHub asks you to select a security mode
Note that, depending on the mode you've chosen, this page asks you to create one or more passwords for accessing VirtualHub. How user and admin passwords work is described in the VirtualHub documentation.
Legacy mode
The legacy mode is the mode that most closely resembles VirtualHub version 1 and YoctoHub. No password is imposed, and VirtualHub accepts both unencrypted (HTTP) AND encrypted (HTTPS) incoming connections. This mode is compatible with older applications or libraries that don't manage passwords or support HTTPS.
However, it should only be used on a secure network, especially if no password is configured. Note that you can safely use this mode if you launch VirtualHub with the -p 127.0.0.1 option. In this case, the application restricts access to processes running on the local machine.
When this mode is selected, Yoctopuce libraries supporting API 2.0 automatically accept self-signed certificates.
Secure mode
The secure mode is the most secure mode, forcing the use of passwords and encrypted communications (HTTPS). This is the mode you should use if VirtualHub is accessible from a public network.
This means that browsers and applications connecting to VirtualHub must correctly manage the SSL certificate installed. If this certificate is a self-signed one, you must either install it on the client machine, or add an exception to automatically accept this certificate. We have a post on this topic. The new programming libraries that use API 2.0 contain a "Prog-RegisterHubHTTPS" example that illustrates certificate management during connection.
Please note that this mode is not compatible with libraries using API 1.10. Similarly, applications using older versions of the library do not work with this mode.
Note that this mode requires a password to connect to VirtualHub.
Mixed mode
The mixed mode is a mixture of the last two modes and offers a reasonable level of security without breaking backward compatibility. VirtualHub accepts unencrypted (HTTP) AND encrypted (HTTPS) incoming connections, but forces the use of a password.
As with the legacy mode, Yoctopuce libraries supporting API 2.0 automatically accept self-signed certificates installed in VirtualHub.
Unlike the legacy mode, 2.0 libraries encrypt communications by default.
Implications for libraries
These different modes have an impact on the way libraries work.
Libraries still using API 1.10 (UWP, Delphi, Objective-C...) only work in legacy or mixed mode. In both these modes, the operation of the libraries remains unchanged. Obviously, if a password has been configured, you'll need to pass it when calling YAPI.RegisterHub.
Where things change is with the 2.0 libraries. As a reminder, the URLs supported by 2.0 libraries are:
- http://
- ws://
- https://
- wss://
- secure://
- auto://
If no protocol is specified in the URL, the library uses the auto:// protocol.
Let's look at the impact of the different modes for each protocol:
http://
This protocol forces the library to use an HTTP connection. It therefore operates in legacy and mixed modes, and uses unencrypted communication. In secure mode, communication is upgraded to HTTPS, with data encryption and SSL certificate verification.
ws://
This protocol forces the library to use a WebSocket connection. It therefore operates in legacy and mixed modes, and uses unencrypted communication. In secure mode, communication is upgraded to Sercure WebSocket with data encryption and SSL certificate verification.
https://
This protocol forces the library to use an HTTPS connection. It works in all modes and guarantees that communication is encrypted and that the certificate is verified. This protocol is not supported on YoctoHubs and VirtualHub v1.
wss://
This protocol forces the library to use a Sercure WebSocket connection. It works in all modes and guarantees that communication is encrypted and that the certificate is verified. This protocol is not supported on YoctoHubs and VirtualHub v1.
secure://
This protocol allows any protocol to be used, as long as the communication is encrypted and the certificate is verified. In plain English, wss:// and https:// are supported. This protocol is not supported on YoctoHubs and VirtualHub v1.
auto://
This is the default protocol if no prefix is used when calling YAPI.RegisterHub. All previous protocols are allowed.
When VirtualHub is in secure mode, communication is encrypted and the certificate verified.
When VirtualHub is in mixed mode, communication is encrypted, but the certificate is not verified.
When VirtualHub is in legacy mode, communication is NOT encrypted.
This protocol also works with YoctoHub and VirtualHub v1, in which case communication is obviously unencrypted.
Conclusion
We've thought long and hard about these different modes to ensure 100% secure communication when necessary, while allowing simpler configurations for uses where security is not an issue.
We hope this post clarifies which type of communication is used depending on your situation. Don't forget that the 2.0 libraries have a new "Prog-RegisterHubHTTPS" example that uses an encrypted connection. Finally, you can read or re-read our previous posts on the subject:
- Why do browsers block VirtualHub v2?
- TLS certificates and the C++ 2.0 library
- Updating the Java, TypeScript and PHP libraries
- Using TLS/SSL with our PHP library
- Using TLS/SSL with our Line 2.0 command library