This week we review the roadmap we outlined at the start of the year. After the C++, C#, Python and VB.net libraries, we've just released version 2.0 of the Java, PHP, and TypeScript libraries. Here's a quick reminder of what's new.
The main new feature of API 2.0 is the addition of communication encryption using TLS. Note that communication encryption is currently only supported by VirtualHub v2.0, VirtualHub for Web and GatewayHub.
To use a secure connection, simply add the "secure://" prefix to the VirtualHub address when calling YAPI.RegisterHub. The "secure://" prefix forces the library to establish an encrypted connection. If the library tries to connect to a hub that does not support data encryption, the call returns an error.
try{
YAPI.RegisterHub("secure://vhub.example.com");
} catch (YAPI_Exception e) {
e.printStackTrace();
}
...
The "secure://" prefix tries to connect using the "WebSocket Secure" protocol first, and falls back to HTTPS if it's not available (e.g. VirtualHub for Web). If you want to force a particular type of connection, you can use the "https://" and "wss://" prefixes.
Certificate management
TLS encryption means certificate management. We've already explained the different types of certificates in a previous post. We'll simply list the functions in our libraries that can be used to manage unknown certificates.
With the exception of the two special cases described below, the API is identical to the other API 2.0 libraries.
The YAPI::AddTrustedCertificates method is used to add certificates to the list of trusted certificates. This function takes as parameter a string containing one or more certificates in PEM format.
// certicate of vhub.example.com in pem format
"-----BEGIN CERTIFICATE-----\n"
"MIIF3jCCA8agAwIBAgIQAf1tMPyjylGoG7xkDjUDLTANBgkqhkiG9w0BAQwFADCB\n"
"iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl\n"
"cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV\n"
"BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTAw\n"
...
"qS3fuQL39ZeatTXaw2ewh0qpKJ4jjv9cJ2vhsE/zB+4ALtRZh8tSQZXq9EfX7mRB\n"
"VXyNWQKV3WKdwrnuWih0hKWbt5DHDAff9Yk2dDLWKMGwsAvgnEzDHNb842m1R0aB\n"
"L6KCq9NjRHDEjf8tM7qtj3u1cIiuPhnPQCjY/MiQu12ZIvVS5ljFH4gxQ+6IHdfG\n"
"jjxDah2nGN59PRbxYvnKkKj9\n"
"-----END CERTIFICATE-----\n";
String error = YAPI.AddTrustedCertificates(CA_PEM);
if (error.lenght() > 0) {
System.out.println(error);
return;
}
YAPI.RegisterHub("secure://vhub.example.com");
...
The YAPI.DownloadHostCertificate method is used to download a server's certificate. This method is useful for obtaining the certificate of a VirtualHub whose certificate is not yet known. Warning: this method bypasses SSL/TLS validation, so make sure your network and machine are not corrupted during execution.
The following code searches the hard disk to see if we already have the certificate for this VirtualHub. If so, we load it from disk and add it to the list of trusted certificates. If this is the first time this VirtualHub has been accessed, a warning message is displayed to the user, asking if the certificate for this new VirtualHub needs to be downloaded and saved. If the answer is yes, you can use the YAPI.DownloadHostCertificate method to obtain the certificate in PEM format and save it to disk.
String host = "secure://vhub.example.com";
String trusted_cert = load_cert_from_fs(host);
if (trusted_cert.isEmpty()) {
// no certificate for host on file system
if (warn_and_ask_user()){
trusted_cert = YAPI,DownloadHostCertificate(host, 5000);
save_cert_to_fs(host, trusted_cert);
} else {
System.exit(1);
}
}
String error = YAPI.AddTrustedCertificates(trusted_cert);
if (!error.isEmpty()) {
System.err.println(error);
System.exit(1);
}
YAPI.RegisterHub(host, errmsg);
...
The YAPI::SetNetworkSecurityOptions method can be used to disable some security checks.
- NO_TRUSTED_CA_CHECK: Disables certificate verification.
- NO_EXPIRATION_CHECK: Disables certificate expiration date checking.
- NO_HOSTNAME_CHECK: Disables hostname checking.
The following code disables all TLS certificate checks.
| YAPI.NO_TRUSTED_CA_CHECK | YAPI.NO_EXPIRATION_CHECK);
The PHP exception
The PHP virtual machine does not allow certificates to be added from a string. The only solution is to use the YAPI::SetTrustedCertificatesList method to specify the list of trusted certificates. This method takes as a parameter the path of a file containing all certificates in PEM format.
if ($error !="") {
die($error);
}
if (YAPI::RegisterHub("wss://vhub.example.com", $errmsg) != YAPI_SUCCESS) {
die("YAPI::RegisterHub failed: ". $errmsg);
}
...
Note that for technical reasons, only one file can be specified. So if you need to connect to several VirtualHub with self-signed certificates, you'll need to use a single file containing all the certificates end-to-end.
The TypeScript exception in a browser
Our TypeScript library can be used in Node.js as well as in a Web browser. When used with Node.js, the methods described above work correctly. However, if you use TypeScript with a browser (Firefox, Chrome, Edge, and so on), none of these methods work.
For security reasons, Web browsers prevent any modification of certificates. This is quite logical, otherwise any web site could corrupt your computer's security. The only solution is to manually install the certificate in the browser, as explained in this post.
How to obtain these libraries
The new versions of these libraries are available through the same channels as v1.10. They can be downloaded from our web site or from GitHub. These three libraries are also available via the usual package managers. These are maven central for Java, Composer/packagist for PHP and npm for Typescript.
Despite the major version change, this new version of the library is backward compatible with API 1.10. So you can update your dependencies without risk.
Conclusion
API 2.0 is now available for our most popular libraries. We will now update our tools that use these libraries (Yocto-Visualization, Yocto-Discovery, and so on) so that they take advantage of TLS encryption and work with VirtualHub for Web.
