Delphi is a slightly outdated programming language, but one that many of our customers still actively use. That's why, this week, we're releasing an update of our library to support our API version 2.0.
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.
if yRegisterHub('secure://vhub.example.com', errmsg) <> YAPI_SUCCESS then
begin
Write('RegisterHub error: '+errmsg);
exit;
end;
...
The "secure://" prefix tries to connect using the "WebSocket Secure" protocol first, and fallbacks 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 implies 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.
yAddTrustedCertificates
The yAddTrustedCertificates function adds certificates to the list of trusted certificates. This function takes as parameter a string containing one or more certificates in PEM format.
CA_PEM: string;
error: string;
...
CA_PEM :=
'-----BEGIN CERTIFICATE-----'+#10+
'MIIF3jCCA8agAwIBAgIQAf1tMPyjylGoG7xkDjUDLTANBgkqhkiG9w0BAQwFADCB'+#10+
'iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl'+#10+
'cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV'+#10+
'BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTAw'+#10+
...
'qS3fuQL39ZeatTXaw2ewh0qpKJ4jjv9cJ2vhsE/zB+4ALtRZh8tSQZXq9EfX7mRB'+#10+
'VXyNWQKV3WKdwrnuWih0hKWbt5DHDAff9Yk2dDLWKMGwsAvgnEzDHNb842m1R0aB'+#10+
'L6KCq9NjRHDEjf8tM7qtj3u1cIiuPhnPQCjY/MiQu12ZIvVS5ljFH4gxQ+6IHdfG'+#10+
'jjxDah2nGN59PRbxYvnKkKj9'+#10+
'-----END CERTIFICATE-----'+#10;
error := yAddTrustedCertificates(CA_PEM);
if error <> '' then
begin
Writeln(error);
exit;
end;
yRegisterHub('secure://vhub.example.com');
...
yDownloadHostCertificate
The yDownloadHostCertificate function is used to download a server certificate. This method is useful for obtaining the certificate of a VirtualHub whose certificate is not yet known. Caution: 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, we display a warning message for 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 yDownloadHostCertificate method to obtain the certificate in PEM format and save it to disk.
host: string;
trusted_cert: string;
...
host := 'secure://vhub.example.com';
trusted_cert := load_cert_from_fs(host);
if trusted_cert = '' then
begin
// no certificate for host on file system
if warn_and_ask_user() then
begin
trusted_cert := yDownloadHostCertificate(host, 5000);
save_cert_to_fs(host, trusted_cert);
end;
error := yAddTrustedCertificates(trusted_cert);
if error <> '' then
Write(error);
exit();
}
yRegisterHub(host, errmsg);
...
ySetNetworkSecurityOptions
You can use the ySetNetworkSecurityOptions method to disable some security checks.
- Y_NO_TRUSTED_CA_CHECK: Disables certificate checking.
- Y_NO_EXPIRATION_CHECK: Disables certificate expiration date checking.
- Y_NO_HOSTNAME_CHECK: Disables hostname checking.
The following code disables all TLS certificate checks.
Conclusion
As usual, this library is available on our website or on GitHub.
Despite the major version change, this new version of the library is backward compatible with API 1.10. And if you're wondering why we skipped version 2.0 and went straight to 2.1 you can read this post.
