Using TLS/SSL with our PHP library

Using TLS/SSL with our PHP library

Our PHP library has supported SSL/TLS encryption for several months now. This makes it possible to use the library to connect to VirtualHub v2.0 and VirtualHub for Web. Let's take a look at how to use this feature to establish a secure connection between the library and VirtualHub.



Using SSL/TLS encryption is very simple. Simply add the prefix "https://" to the VirtualHub address when calling YAPI::RegisterHub.

YAPI::RegisterHub("https://secure.example.com/vhub4web");
$module = YModule::FirstModule();
while (!is_null($module)) {
    printf("%s (%s)<br>\n", $module-&gt;get_serialNumber(),
           $module-&gt;get_productName());
    $module=$module-&gt;nextModule();
}
YAPI::FreeAPI();



Please note that, unlike the other libraries we offer, the PHP library does not support Websocket connections. It is therefore not possible to use the "wss://" prefix for secure Websocket connections.

Certificates in the PHP library


Note: we explained how certificates work in a previous post.

The code we've just shown works as long as the VirtualHub certificate is valid. If VirtualHub uses a self-signed certificate, communication cannot be established, as the PHP library is not aware of this certificate.

In this case, there are two solutions: bypass certificate checking or install the certificate.

Bypassing certificate checking


Checking the server's certificate is essential to guarantee 100% secure communication, but we've added a method for partially or completely disabling this feature.

The YAPI::SetNetworkSecurityOptions method can be used to disable some security checks.

  • NO_TRUSTED_CA_CHECK: Disables certificate checking.
  • NO_HOSTNAME_CHECK: Disables hostname checking.


The following code disables all TLS certificate checks.

YAPI::SetNetworkSecurityOptions( YAPI::NO_HOSTNAME_CHECK | YAPI::NO_TRUSTED_CA_CHECK);



Installing the certificate


To enable true authentication, you need to install the remote VirtualHub's self-signed certificate.

The first step is to obtain VirtualHub's public certificate. The simplest solution is to connect to VirtualHub's web interface with a browser and save the certificate. Most browsers allow you to save the certificate in PEM format.

For example, in Firefox, click on the padlock next to the URL to access the connection details and then display the certificate. From there, you can download the certificate.

In Firefox, you can save the certificate by clicking on the padlock
In Firefox, you can save the certificate by clicking on the padlock



The other option is to use our PHP library and the YAPI::DownloadHostCertificate method. This method establishes a connection with the host passed as an argument and returns the remote certificate.

For example, the following code stores in the vhub_example_com.pem file the certificate for VirtualHub for Web installed on the server https://vhub.example.com.

...
$host = "https://vhub.example.com";
$remote_cert = YAPI::DownloadHostCertificate(host, 5000);
file_put_contents("vhub_example_com.pem",$remote_cert);
...



When the certificate is stored on disk, you can either modify PHP's configuration so that it automatically recognizes this certificate, or use the YAPI::SetTrustedCertificatesList method.

The YAPI::SetTrustedCertificatesList method is used to specify the list of trusted certificates. This method takes as a parameter the path of a file containing all certificates in PEM format.

$error = YAPI::SetTrustedCertificatesList("vhub_example_com.pem");
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 instances with self-signed certificates, you'll need to use a single file containing all the certificates end-to-end.

...
$remote_cert1 = YAPI::DownloadHostCertificate("https://vhub1.example.com", 5000);
$remote_cert2 = YAPI::DownloadHostCertificate("https://vhub2.example.com", 5000);
file_put_contents("allcert.pem",$$remote_cert1.$remote_cert2);
...



Conclusion


In summary, our PHP library supports secure connections with VirtualHub. Simply add the "https://" prefix to the VirtualHub address when calling YAPI::RegisterHub to activate this feature.

However, if VirtualHub uses a self-signed certificate, don't forget to install the certificate on your system.

Add a comment No comment yet Back to blog












Yoctopuce, get your stuff connected.