Version 2.0 of the C++ library supports the TLS protocol and allows encrypted communication between the library and the VirtualHub 2.0. This week we have added methods to configure the TLS authentication more precisely, to manage the list of certificates recognized by the library.
We will start with a very quick reminder of how the TLS protocol (and before it SSL) works.
The TLS protocol has two purposes: the first one is to encrypt the communication in order to avoid that a third party can listen to the communication. The second is to reliably authenticate the server to prevent an attacker from impersonating the server (Man-in-the-middle attack).
SSL/TLS authentication is based on a digital certificate chain. When establishing a connection, the client checks the validity of the certificate chain and makes sure that at lest one certificate in the chain has been emitted by an authority trusted by the client. To establish a 100% secure connection, the client must know the certificates emitters for all the servers it will access.
The certificates in the C++ library
In order to allow a real authentication, the library checks that the server certificate is present in the list of trusted certificates. If the certificate is not registered, the library will return an error when establishing the connection with the VirtualHub 2.
The YAPI::AddTrustedCertificates method allows to add certificates to the trusted certificate list. This function takes as parameter a string which contains 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 !="") {
cerr <<error << endl;
exit(1);
}
if (YAPI::RegisterHub("wss://vhub.example.com", errmsg) != YAPI_SUCCESS) {
cerr << "YAPI::RegisterHub failed: " << errmsg << endl;
}
...
In this example, we have hardcoded the certificate in the code, but you are free to store these certificates, either on the disk or in the Windows registry.
We have also added a YAPI::DownloadHostCertificate method that allows to download the certificate of a server. This method is useful to get the certificate of a VirtualHub whose certificate is not yet known.
For example, the following code searches the hard disk if we already have the certificate for the VirtualHub. If so, we load it from the disk and add it to the list of trusted certificates. If it's the first time we access this VirtualHub, we'll display a warning message to the user asking him if we have to download and save the certificate for this new VirtualHub. In case of a positive answer, we can use the YAPI::DownloadHostCertificate method to obtain the certificate in PEM format and save it on the disk.
string host = "wss://vhub.example.com";
string trusted_cert = load_cert_from_fs(host);
if (trusted_cert == "") {
// 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 {
exit(1);
}
}
string error = YAPI::AddTrustedCertificates(trusted_cert);
if (error !="") {
cerr << error << endl;
exit(1);
}
if (YAPI::RegisterHub(host, errmsg) != YAPI_SUCCESS) {
cerr << "YAPI::RegisterHub failed:" << errmsg << endl;
}
...
YAPI::SetNetworkSecurityOptions method
The check of the server certificate is essential to guarantee a 100% secure communication, but we have added a method that allows to partially or completely disable this feature.
The YAPI::SetNetworkSecurityOptions method allows to disable some security checks.
- NO_TRUSTED_CA_CHECK: Disables certificate checking.
- NO_EXPIRATION_CHECK: Disables certificate expiration date checking.
- NO_HOSTNAME_CHECK: Disable hostname checking
The following code disables all TLS certificate checks.
| YAPI::NO_TRUSTED_CA_CHECK | YAPI::NO_EXPIRATION_CHECK);
The NO_EXPIRATION_CHECK option can be useful if you need to connect to a machine that has an expired certificate.
Conclusion
As a reminder, the C++ v2.0 library is still in preview. This library implements all the features of version 1.0 plus others (like TLS or IPv6). However, we may still change signature of some functions that were added in version v2.0.
It is available on the library download page in the preview section.