Cette semaine nous faisons le point sur le roadmap que nous avions exposé en début d'année. Après les librairies C++, C#, Python et VB.net, nous venons de publier la version 2.0 des librairies Java, PHP et TypeScript. Petit rappel de ce qui change.
La principale nouveauté de l'API 2.0 est l'ajout du chiffrage de la communication à l'aide de TLS. Notez que le chiffrement des communications n'est actuellement supporté que par VirtualHub v2.0, VirtualHub for Web et GatewayHub.
Pour utiliser une connexion sécurisée, il suffit d'ajouter le préfixe "secure://" à l'adresse de VirtualHub lors de l'appel à YAPI.RegisterHub. Le préfixe "secure://" force la libraire à établir une connexion chiffrée. Si la librairie essaie de se connecter à un hub qui ne supporte pas le chiffrement des données, l'appel retournera une erreur.
try{
YAPI.RegisterHub("secure://vhub.example.com");
} catch (YAPI_Exception e) {
e.printStackTrace();
}
...
Le préfixe "secure://" essaie de se connecter en priorité à l'aide du protocole "WebSocket Secure" et effectue un fallback sur HTTPS s'il n'est pas disponible (Ex VirtualHub for Web). Si vous voulez forcer un type particulier de connexion, vous pouvez utiliser les préfixes "https://" et "wss://".
La gestion des certificats
Qui dit chiffrement TLS, dit gestion des certificats. Nous avons déjà expliqué dans un précédent article les différents types de certificats. Nous allons simplement lister les fonctions de nos librairies qui permettent de gérer les certificats inconnus.
Hormis les deux cas particuliers décrits plus bas, l'API est identique aux autres libraires utilisant l'API 2.0.
La méthode YAPI::AddTrustedCertificates permet d'ajouter des certificats à la liste de certificats de confiance. Cette fonction prend en paramètre une chaine de caractères qui contient un ou plusieurs certificats au format PEM.
// 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");
...
La méthode YAPI.DownloadHostCertificate permet de télécharger le certificat d'un serveur. Cette méthode est pratique pour obtenir le certificat d'un VirtualHub dont le certificat n'est pas encore connu. Attention, cette méthode bypasse la validation SSL/TLS, assurez-vous que votre réseau et votre machine ne soient pas corrompus lors de l'exécution.
Le code suivant cherche sur le disque dur si nous avons déjà le certificat pour ce VirtualHub. Si c'est le cas, on le charge du disque et on l'ajoute à la liste des certificats de confiance. Si c'est la première fois qu'on accède à ce VirtualHub on afficher un message d'avertissement à l'utilisateur pour lui demander s’il faut télécharger et sauver le certificat de ce nouveau VirtualHub. En cas de réponse positive, on peut utiliser la méthode YAPI.DownloadHostCertificate pour obtenir le certificat au format PEM et le sauver sur le disque.
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);
...
La méthode YAPI::SetNetworkSecurityOptions permet de désactiver certains checks de sécurité.
- NO_TRUSTED_CA_CHECK: Désactive la vérification des certificats.
- NO_EXPIRATION_CHECK: Désactive la vérification de la date d'expiration d'un certificat.
- NO_HOSTNAME_CHECK: Désactive la vérification du hostname
Le code suivant désactive toutes les vérifications des certificats TLS.
| YAPI.NO_TRUSTED_CA_CHECK | YAPI.NO_EXPIRATION_CHECK);
L'exception PHP
La machine virtuelle PHP ne permet pas d'ajouter des certificats depuis une chaine de caractères. La seule solution est d'utiliser la méthode YAPI::SetTrustedCertificatesList qui permet de spécifier la liste de certificats de confiance. Cette méthode prend en paramètre le path d'un fichier contenant tous les certificats au format PEM.
if ($error !="") {
die($error);
}
if (YAPI::RegisterHub("wss://vhub.example.com", $errmsg) != YAPI_SUCCESS) {
die("YAPI::RegisterHub failed: ". $errmsg);
}
...
Notez que pour des raisons techniques, il n'est possible de spécifier qu'un seul fichier. Donc si vous devez vous connecter à plusieurs VirtualHub avec des certificats auto-signés, il faudra utiliser un seul fichier qui contient les certificats mis bout à bout.
L'exception TypeScript dans un browser
Notre librairie TypeScript peut fonctionner sous Node.js mais aussi dans un browser Web. Lorsqu'elle est utilisée avec Node.js, les méthodes décrites plus haut fonctionnent correctement. Cependant, si vous utilisez TypeScript avec un browser (Firefox, Chrome, Edge, etc.), aucune de ces méthodes ne fonctionnera.
Pour des raisons de sécurité, les browsers Web empêchent toute modification des certificats. C'est assez logique, sinon n'importe quel site Web pourrait corrompre la sécurité de votre PC. La seule solution est d'installer manuellement le certificat dans le browser, comme nous l'avons expliqué dans cet article.
Comment obtenir ces librairies
Les nouvelles versions de ces librairies sont disponibles par les mêmes canaux que la v1.10. Elles peuvent être téléchargées depuis notre site Web ou depuis GitHub. Ces trois librairies sont aussi disponibles via des packages manager habituels. A savoir, maven central pour Java, Composer/packagist pour PHP et npm pour Typescript.
Malgré le changement de version majeur, cette nouvelle version de la librairie est backward compatible avec l'API 1.10. Vous pouvez donc mettre à jour vos dépendances sans risque.
Conclusion
L'API 2.0 est maintenant disponible pour nos libraires les plus populaires. Nous allons maintenant mettre à jour nos utilitaires qui utilisent ces libraires (Yocto-Visualization, Yocto-Discovery, etc.) pour qu'ils profitent du chiffrement TLS et fonctionnent avec le VirtualHub for Web.
