Portage de la bibliothèque Secure Sockets - FreeRTOS

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Portage de la bibliothèque Secure Sockets

Vous pouvez utiliser la bibliothèque FreeRTOS Secure Sockets pour créer et configurer un socket TCP, vous connecter à l'agent MQTT et envoyer/recevoir des données TCP. La bibliothèque Secure Sockets encapsule également la fonctionnalité TLS. Seul un socket TCP standard est nécessaire pour créer un socket protégé par TLS. Pour de plus amples informations, veuillez consulterBibliothèque FreeRTOS Secure Socketsdans le guide de l'utilisateur FreeRTOS.

FreeRTOS inclut une implémentation Secure Sockets pour leFreeRTOS+TCPetIP léger (lwIP)Piles TCP/IP, qui sont utilisées en association avecmbedTLS. Si vous utilisez soit FreeRTOS+TCP, soit la pile TCP/IP lwIP, vous n'avez pas besoin de procéder au portage de la bibliothèque Secure Sockets.

Note
  • Même si vous n'avez pas besoin de créer un portage de la bibliothèque Secure Sockets, votre plateforme doit toujours réussir les tests de qualification de la bibliothèque Secure Sockets. La qualification est basée sur les résultats de AWS IoT Device Tester.

  • Votre implémentation TLS doit prendre en charge leSuites de chiffrement TLS prises en charge parAWS IoT.

  • Si vous modifiez la configuration TLS de la bibliothèque Secure Sockets, cela peut entraîner un échec lorsque vous tentez de vous connecter au serveur echo. Toutes les suites de chiffrement prises en charge par le serveur echo ne sont pas prises en charge par la bibliothèque Secure Sockets, et si vous activez une suite de chiffrement que la bibliothèque ne prend pas en charge actuellement (par exemple, SHA384), vous ne pourrez peut-être pas vous connecter.

  • Si votre plateforme décharge des fonctionnalités TCP/IP sur un autre processeur du réseau, vous devez procéder au portage de la bibliothèque FreeRTOS Secure Sockets sur votre appareil.

Prerequisites

Pour le portage de la bibliothèque Secure Sockets, vous avez besoin des éléments suivants :

  • Un portage de la bibliothèque Wi-Fi (obligatoire uniquement si vous utilisez le Wi-Fi pour vous connecter au réseau).

    Pour plus d'informations sur le portage la bibliothèque Wi-Fi, consultez Portage de la bibliothèque Wi-Fi Library.

  • Si votre carte est dotée d'une connectivité cellulaire, vous devez fournir une bibliothèque Secure Sockets qui utilise le modem cellulaire comme transport. Vous pouvez mettre en œuvre la bibliothèque Secure Sockets de deux manières :

    • Implémentez l'API Secure Sockets en utilisant directement les commandes AT de votre modem.

    • Utilisez la bibliothèque Cellular Interface fournie par FreeRTOS, qui masque les commandes AT et fournit une API de type socket. Pour plus d'informations, consultez Portage de la bibliothèque Cellular Interface.

  • Un port d'une pile TCP/IP.

    Pour plus d'informations sur le portage d'une pile TCP/IP, consultez Portage d'une pile TCP/IP.

  • Un serveur écho.

    FreeRTOS inclut un serveur echo, écrit en langage Go, dans lefreertos/tools/echo_serverrépertoire. Pour plus d'informations, consultez Configuration d'un serveur echo.

Porting

Si votre plateforme décharge des fonctionnalités TCP/IP sur une puce de réseau distincte, vous devez mettre en œuvre toutes les fonctions pour lesquelles il existe des stubs dans freertos/vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c.

Testing

Si vous utilisez un IDE pour générer des projets de test, vous devez configurer le portage de votre bibliothèque dans le projet IDE.

Configuration du projet de test IDE

Si vous utilisez un IDE pour le portage et le test, vous devez ajouter des fichiers source au projet de test IDE avant de pouvoir tester votre code porté.

Important

Dans les étapes suivantes, assurez-vous d’ajouter les fichiers source à votre projet IDE depuis leur emplacement sur disque. Ne créez pas de copies de vos fichiers source.

Pour configurer la bibliothèque Secure Sockets dans le projet IDE

  1. Si vous utilisez la pile TCP/IP FreeRTOS+TCP, ajoutez freertos/libraries/abstractions/secure_sockets/freertos_plus_tcp/iot_secure_sockets.c au projet IDE aws_tests.

    Si vous utilisez la pile TCP/IP lwIP, ajoutez freertos/libraries/abstractions/secure_sockets/lwip/iot_secure_sockets.c au projet IDE aws_tests.

    Si vous utilisez votre propre port TCP/IP, ajoutez freertos/vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c au projet IDE aws_tests.

  2. Ajoutez secure_sockets/test/aws_test_tcp.c au projet IDE aws_tests.

Configuration du fichier CMakeLists.txt

Si vous utilisez CMake pour générer votre projet de test, vous devez définir une cible de couche portable pour la bibliothèque dans votre fichier de liste CMake.

Pour définir la cible de couche portable d'une bibliothèque dans CMakeLists.txt, suivez les instructions de Couches portables FreeRTOS.

Le fichier de liste de modèles CMakeLists.txt sous freertos/vendors/vendor/boards/board/CMakeLists.txt inclut des exemples de définition cible de couche portable. Vous pouvez supprimer la mise en commentaire de la définition de la bibliothèque que vous portez et modifier celle-ci pour qu'elle corresponde à votre plateforme.

Voici un exemple de définition cible d'une couche portable pour la bibliothèque Secure Sockets.

# Secure sockets afr_mcu_port(secure_sockets) # Link to AFR::secure_sockets_freertos_tcp if you want use default implementation based on # FreeRTOS-Plus-TCP. target_link_libraries( AFR::pkcs11::mcu_port INTERFACE AFR::secure_sockets_freertos_tcp ) # Or provide your own implementation. target_sources( AFR::secure_sockets::mcu_port INTERFACE "$path/iot_secure_sockets.c" )

Configuration de votre environnement de test local

Après avoir configuré la bibliothèque dans votre projet IDE, vous devez configurer des fichiers à tester.

Pour configurer la source et les fichiers d'en-tête pour les tests Secure Sockets

  1. Ouvrez freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c et, dans la fonction SYSTEM_Init(), assurez-vous que la ligne qui appelle SOCKETS_Init() n'est pas commentée.

  2. Démarrez un serveur echo.

    Si vous n'avez pas procédé au portage de la bibliothèque TLS sur votre plateforme, vous ne pouvez tester votre port Secure Sockets qu’à l'aide d'un serveur echo non sécurisé (freertos/tools/echo_server/echo_server.go). Pour de plus amples informations sur la configuration et l'exécution d'un serveur echo non sécurisé, veuillez consulter Configuration d'un serveur echo.

  3. Dans aws_test_tcp.h, définissez l'adresse IP en fonction des valeurs correctes pour votre serveur. Par exemple, si l’adresse IP de votre serveur est 192.168.2.6, définissez les valeurs suivantes dans aws_test_tcp.h:

    Macro Value (Valeur)
    tcptestECHO_SERVER_ADDR0 192
    tcptestECHO_SERVER_ADDR1 168
    tcptestECHO_SERVER_ADDR2 2
    tcptestECHO_SERVER_ADDR3 6
  4. Ouvrez aws_test_tcp.h et définissez la macro tcptestSECURE_SERVER sur 0 pour exécuter les tests Secure Sockets sans TLS.

  5. Ouvrez freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner.config.h et définissez la macro testrunnerFULL_TCP_ENABLED sur 1 activer les tests de sockets.

  6. Ouvrez freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c et supprimez les directives du compilateur #endif et #if 0 dans la définition vApplicationIPNetworkEventHook ( void ) pour activer la tâche de test.

    Note

    Cette modification est nécessaire pour pouvoir effectuer le portage des bibliothèques restantes.

Important

Aux fins de la qualification, vous devez réussir les tests Secure Sockets teste avec TLS. Une fois le portage de la bibliothèque TLS effectué, réexécutez les tests Secure Sockets avec les tests TLS activés, au moyen d’un serveur echo compatible TLS.

Concernant le portage de la bibliothèque TLS, consultez Portage de la bibliothèque TLS.

Pour configurer les tests Secure Sockets après le portage de la bibliothèque TLS

  1. Démarrez un serveur echo sécurisé.

    Pour plus d'informations, veuillez consulter Configuration d'un serveur echo.

  2. Définissez le port et l'adresse IP dans freertos/tests/include/aws_test_tcp.h afin de rectifier les valeurs pour votre serveur. Par exemple, si l’adresse IP de votre serveur est 192.168.2.6 et que le serveur écoute sur 9000, définissez les valeurs suivantes dans freertos/tests/include/aws_test_tcp.h :

    Macro Value (Valeur)
    tcptestECHO_SERVER_TLS_ADDR0 192
    tcptestECHO_SERVER_TLS_ADDR1 168
    tcptestECHO_SERVER_TLS_ADDR2 2
    tcptestECHO_SERVER_TLS_ADDR3 6
    tcptestECHO_PORT_TLS 9000
  3. Ouvrez freertos/tests/include/aws_test_tcp.h et définissez la macro tcptestSECURE_SERVER sur 1 afin d'activer les tests TLS.

  4. Téléchargez un certificat racine approuvé. Pour plus d'informations sur les certificats racine approuvés obtenir des liens de téléchargement, consultez la section traitant de l’authentification serveur dans le Manuel du développeur AWS IoT. Nous vous recommandons d'utiliser les certificats Amazon Trust Services.

  5. Dans une fenêtre du navigateur, ouvrez freertos/tools/certificate_configuration/PEMfileToCString.html.

  6. Sous PEM Certificate or Key (Clé ou certificat PEM), sélectionnez le fichier du certificat CA racine que vous avez téléchargé.

  7. Sélectionnez Display formatted PEM string to be copied into aws_clientcredential_keys.h (Afficher la chaîne PEM formatée à copier dans aws_clientcredential_keys.h), puis copiez la chaîne du certificat.

  8. Ouvrez aws_test_tcp.h et collez la chaîne formatée de certificat dans la définition de tcptestECHO_HOST_ROOT_CA.

  9. Utilisez le second jeu de commandes OpenSSL dans freertos/tools/echo_server/readme-gencert.txt pour générer un certificat client et une clé privée signés par l'autorité de certification. Le certificat et la clé permettent au serveur echo personnalisé de faire confiance au certificat client que votre appareil lors de l’authentification TLS.

  10. Formatez le certificat et la clé à l’aide de l'outil de formatage freertos/tools/certificate_configuration/PEMfileToCString.html.

  11. Avant de créer et d'exécuter le projet de test sur votre appareil, ouvrez aws_clientcredential_keys.h, puis copiez le certificat client et la clé privée, au format PEM, dans les définitions de keyCLIENT_CERTIFICATE_PEM et keyCLIENT_PRIVATE_KEY_PEM.

Exécution des tests

Pour exécuter les tests Secure Sockets

  1. Générez le projet de test, puis flashez-le sur votre appareil pour l'exécuter.

  2. Vérifiez les résultats de test dans la console UART.

    ...

    Si chacun des tests est réussi, la phase de test est alors terminée.

Validation

Pour qualifier officiellement un périphérique pour FreeRTOS, vous devez valider le code source porté de l'appareil avecAWS IoTDevice Tester. Suivez les instructions de la sectionUtilisation d’AWS IoTFreeRTOS Device Tester pourdans le guide de l'utilisateur FreeRTOS afin de configurer Device Tester pour la validation de port. Pour tester le port d'une bibliothèque spécifique, le groupe de test correct doit être activé dans le fichier device.json du dossier configs de Device Tester.

Une fois que vous avez terminé le portage de la bibliothèque FreeRTOS Secure Sockets sur votre appareil, vous pouvez démarrer le portage de la bibliothèque CorePKCS11. Pour obtenir des instructions, consultez Portage de la bibliothèque CorePKCS11.