mbedtls
Mbed TLS 3.6.2
Mbed TLS est une bibliothèque C qui implémente des primitives cryptographiques, la manipulation de certificats X.509 et les protocoles SSL/TLS et DTLS. Sa petite empreinte de code le rend adapté aux systèmes embarqués.
Mbed TLS inclut une implémentation de référence de l'API de cryptographie PSA. Il s'agit actuellement d'un aperçu à des fins d'évaluation uniquement.
Mbed TLS devrait être intégré à la plupart des systèmes. Certaines options spécifiques à la plate-forme sont disponibles dans le fichier de configuration entièrement documenté include/mbedtls/mbedtls_config.h , qui est également l'endroit où les fonctionnalités peuvent être sélectionnées. Ce fichier peut être modifié manuellement ou de manière plus programmatique à l'aide du script Python 3 scripts/config.py (utilisez --help pour les instructions d'utilisation).
Les options du compilateur peuvent être définies à l'aide de variables d'environnement conventionnelles telles que CC et CFLAGS lors de l'utilisation du système de construction Make et CMake (voir ci-dessous).
Nous fournissons des configurations non standard axées sur des cas d'utilisation spécifiques dans le répertoire configs/ . Vous pouvez en savoir plus à ce sujet dans configs/README.txt
La documentation principale de Mbed TLS est disponible via ReadTheDocs.
La documentation de l'API de cryptographie PSA est disponible sur GitHub.
Pour générer une copie locale de la documentation de la bibliothèque au format HTML, adaptée à votre configuration au moment de la compilation :
make apidoc .apidoc/index.html ou apidoc/modules.html .Pour d’autres sources de documentation, consultez le document SUPPORT.
Il existe actuellement trois systèmes de build actifs utilisés dans les versions Mbed TLS :
Les principaux systèmes utilisés pour le développement sont CMake et GNU Make. Ces systèmes sont toujours complets et à jour. Les autres doivent refléter toutes les modifications présentes dans le système de build CMake et Make, bien que les fonctionnalités ne puissent pas y être portées automatiquement.
Les systèmes de build Make et CMake créent trois bibliothèques : libmbedcrypto/libtfpsacrypto, libmbedx509 et libmbedtls. Notez que libmbedtls dépend de libmbedx509 et libmbedcrypto/libtfpsacrypto, et libmbedx509 dépend de libmbedcrypto/libtfpsacrypto. En conséquence, certains éditeurs de liens s'attendront à ce que les indicateurs soient dans un ordre spécifique, par exemple l'éditeur de liens GNU veut -lmbedtls -lmbedx509 -lmbedcrypto .
Vous avez besoin des outils suivants pour créer la bibliothèque avec les makefiles fournis :
La branche development et la branche de support à long terme mbedtls-3.6 de Mbed TLS utilisent un sous-module Git (framework). Cela n'est pas nécessaire pour simplement compiler la bibliothèque au niveau d'une balise de version. Cela n'est pas nécessaire pour consommer une archive de version (zip ou tar).
Le code source de Mbed TLS comprend certains fichiers générés automatiquement par des scripts et dont le contenu dépend uniquement de la source Mbed TLS, et non de la plateforme ou de la configuration de la bibliothèque. Ces fichiers ne sont pas inclus dans la branche de développement de Mbed TLS, mais les fichiers générés sont inclus dans les versions officielles. Cette section explique comment générer les fichiers manquants dans la branche de développement.
Les outils suivants sont requis :
python3 -m pip install --user -r scripts/basic.requirements.txt
python au lieu de python3 . Pour installer les packages à l’échelle du système, omettez l’option --user . Si vous effectuez une compilation croisée, vous devez définir la variable d'environnement CC sur un compilateur C pour la plate-forme hôte lors de la génération des fichiers indépendants de la configuration.
L'une des méthodes suivantes est disponible pour générer les fichiers indépendants de la configuration :
make avec n'importe quelle cible, ou simplement make , générera automatiquement les fichiers requis.make generated_files pour générer tous les fichiers indépendants de la configuration.tests/scripts/check-generated-files.sh -u pour générer tous les fichiers indépendants de la configuration.scriptsmake_generated_files.bat pour générer tous les fichiers indépendants de la configuration.Nous avons besoin de GNU Make. Pour construire la bibliothèque et les exemples de programmes, GNU Make et un compilateur C suffisent. Certaines des cibles de build les plus avancées nécessitent des outils Unix/Linux.
Nous n'utilisons intentionnellement qu'un minimum de fonctionnalités dans les makefiles afin de les garder aussi simples et indépendants des différentes chaînes d'outils que possible, afin de permettre aux utilisateurs de se déplacer plus facilement entre les différentes plates-formes. Il est recommandé aux utilisateurs qui ont besoin de plus de fonctionnalités d'utiliser CMake.
Pour construire à partir du code source à l'aide de GNU Make, entrez simplement sur la ligne de commande :
make
Pour exécuter les tests, saisissez :
make check
Les tests nécessitent que Python soit construit et que Perl soit exécuté. Si aucun d’entre eux n’est installé, vous pouvez ignorer la construction des tests avec :
make no_test
Vous pourrez toujours exécuter un ensemble de tests beaucoup plus restreint avec :
programs/test/selftest
Afin de créer pour une plate-forme Windows, vous devez utiliser WINDOWS_BUILD=1 si la cible est Windows mais que l'environnement de construction est de type Unix (par exemple lors d'une compilation croisée ou d'une compilation à partir d'un shell MSYS), et WINDOWS=1 si le l'environnement de construction est un shell Windows (par exemple utilisant mingw32-make) (dans ce cas certaines cibles ne seront pas disponibles).
La définition de la variable SHARED dans votre environnement créera des bibliothèques partagées en plus des bibliothèques statiques. La définition DEBUG vous donne une version de débogage. Vous pouvez remplacer CFLAGS et LDFLAGS en les définissant dans votre environnement ou sur la ligne de commande make ; les options d'avertissement du compilateur peuvent être remplacées séparément à l'aide de WARNING_CFLAGS . Certaines options spécifiques au répertoire (par exemple, les directives -I ) sont toujours conservées.
Veuillez noter que la définition CFLAGS remplace sa valeur par défaut de -O2 et la définition WARNING_CFLAGS remplace sa valeur par défaut (en commençant par -Wall -Wextra ), donc si vous souhaitez simplement ajouter des options d'avertissement à celles par défaut, vous pouvez le faire en définissant CFLAGS=-O2 -Werror par exemple. La définition de WARNING_CFLAGS est utile lorsque vous souhaitez vous débarrasser de son contenu par défaut (par exemple parce que votre compilateur n'accepte pas -Wall comme option). Les options spécifiques au répertoire ne peuvent pas être remplacées à partir de la ligne de commande.
En fonction de votre plateforme, vous pourriez rencontrer certains problèmes. Veuillez vérifier les Makefiles dans library/ , programs/ et tests/ pour les options à ajouter ou à supprimer manuellement pour des plates-formes spécifiques. Vous pouvez également consulter la base de connaissances Mbed TLS pour obtenir des articles sur votre plateforme ou votre problème.
Si vous estimez que vous devez également faire autre chose, veuillez nous le faire savoir afin que nous puissions l'ajouter à la base de connaissances Mbed TLS.
Afin de construire la source en utilisant CMake dans un répertoire séparé (recommandé), entrez simplement sur la ligne de commande :
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
Pour exécuter les tests, saisissez :
ctest
Les suites de tests nécessitent que Python soit construit et que Perl soit exécuté. Si aucun de ces éléments n'est installé, vous souhaiterez désactiver les suites de tests avec :
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Si vous avez désactivé les suites de tests tout en gardant les programmes activés, vous pouvez toujours exécuter un ensemble de tests beaucoup plus réduit avec :
programs/test/selftest
Pour configurer CMake pour créer des bibliothèques partagées, utilisez :
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Il existe de nombreux modes de construction différents disponibles dans le système de construction CMake. La plupart d'entre eux sont disponibles pour gcc et clang, bien que certains soient spécifiques au compilateur :
Release . Cela génère le code par défaut sans aucune information inutile dans les fichiers binaires.Debug . Cela génère des informations de débogage et désactive l'optimisation du code.Coverage . Cela génère des informations de couverture de code en plus des informations de débogage.ASan . Cela instrumente le code avec AddressSanitizer pour vérifier les erreurs de mémoire. (Cela inclut LeakSanitizer, avec la version récente de gcc et clang.) (Avec la version récente de clang, ce mode instrumente également le code avec UndefinedSanitizer pour vérifier un comportement non défini.)ASanDbg . Identique à ASan mais plus lent, avec des informations de débogage et de meilleures traces de pile.MemSan . Cela instrumente le code avec MemorySanitizer pour vérifier les lectures de mémoire non initialisées. Expérimental, nécessite un clang récent sur Linux/x86_64.MemSanDbg . Identique à MemSan mais plus lent, avec des informations de débogage, de meilleures traces de pile et un suivi d'origine.Check . Cela active les avertissements du compilateur qui dépendent de l'optimisation et traite tous les avertissements comme des erreurs.Changer de mode de construction dans CMake est simple. Pour le mode débogage, entrez sur la ligne de commande :
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Pour répertorier les autres options CMake disponibles, utilisez :
cmake -LH
Notez qu'avec CMake, vous ne pouvez pas ajuster le compilateur ou ses indicateurs après l'invocation initiale de cmake. Cela signifie que CC=your_cc make et make CC=your_cc ne fonctionneront pas (de la même manière avec CFLAGS et d'autres variables). Ces variables doivent être ajustées lors du premier appel de cmake, par exemple :
CC=your_cc cmake /path/to/mbedtls_source
Si vous avez déjà appelé cmake et souhaitez modifier ces paramètres, vous devez supprimer le répertoire de construction et le créer à nouveau.
Notez qu’il est possible de construire sur place ; cela écrasera cependant les Makefiles fournis (voir scripts/tmp_ignore_makefiles.sh si vous souhaitez empêcher git status de les afficher comme modifiés). Pour ce faire, depuis le répertoire source Mbed TLS, utilisez :
cmake .
make
Si vous souhaitez modifier CC ou CFLAGS par la suite, vous devrez supprimer le cache CMake. Cela peut être fait avec la commande suivante en utilisant GNU find :
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Vous pouvez maintenant effectuer la modification souhaitée :
CC=your_cc cmake .
make
Concernant les variables, notez également que si vous définissez CFLAGS lors de l'appel de cmake, votre valeur de CFLAGS ne remplace pas le contenu fourni par cmake (en fonction du mode de construction comme vu ci-dessus), elle y est simplement ajoutée.
Mbed TLS fournit un fichier de configuration de package à utiliser en tant que dépendance dans d'autres projets CMake. Vous pouvez inclure vous-même les cibles CMake de Mbed TLS avec :
find_package(MbedTLS)
Si vous y êtes invité, définissez MbedTLS_DIR sur ${YOUR_MBEDTLS_INSTALL_DIR}/cmake . Cela crée les cibles suivantes :
MbedTLS::tfpsacrypto (bibliothèque Crypto)MbedTLS::mbedtls (bibliothèque TLS)MbedTLS::mbedx509 (bibliothèque X509) Vous pouvez ensuite les utiliser directement via target_link_libraries() :
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
Cela reliera les bibliothèques Mbed TLS à votre bibliothèque ou application, et ajoutera ses répertoires d'inclusion à votre cible (de manière transitive, dans le cas des bibliothèques de liens PUBLIC ou INTERFACE ).
Mbed TLS prend en charge la construction en tant que sous-projet CMake. On peut utiliser add_subdirectory() à partir d'un projet CMake parent pour inclure Mbed TLS en tant que sous-projet.
Les fichiers de build pour Microsoft Visual Studio sont générés pour Visual Studio 2017.
Le fichier de solution mbedTLS.sln contient tous les projets de base nécessaires à la construction de la bibliothèque et de tous les programmes. Les fichiers des tests ne sont pas générés ni compilés, car ils nécessitent également des environnements Python et Perl. Cependant, le programme d'autotest dans programs/test/ est toujours disponible.
Dans la branche de développement de Mbed TLS, les fichiers de solution Visual Studio doivent d'abord être générés comme décrit dans « Fichiers sources générés dans la branche de développement ».
Nous avons inclus des exemples de programmes pour de nombreuses fonctionnalités et utilisations différentes dans programs/ . Veuillez noter que l'objectif de ces exemples de programmes est de démontrer des fonctionnalités spécifiques de la bibliothèque et que le code devra peut-être être adapté pour créer une application réelle.
Mbed TLS inclut une suite de tests élaborée dans tests/ qui nécessite initialement que Python génère les fichiers de tests (par exemple test_suite_ssl.c ). Ces fichiers sont générés à partir d'un function file (par exemple suites/test_suite_ssl.function ) et d'un data file (par exemple suites/test_suite_ssl.data ). Le function file contient les fonctions de test. Le data file contient les cas de test, spécifiés sous forme de paramètres qui seront transmis à la fonction de test.
Pour les machines sur lesquelles un shell Unix et OpenSSL (et éventuellement GnuTLS) sont installés, des scripts de test supplémentaires sont disponibles :
tests/ssl-opt.sh exécute des tests d'intégration pour diverses options TLS (renégociation, reprise, etc.) et teste l'interopérabilité de ces options avec d'autres implémentations.tests/compat.sh teste l'interopérabilité de chaque suite de chiffrement avec d'autres implémentations.tests/scripts/test-ref-configs.pl test se construit dans diverses configurations réduites.tests/scripts/depends.py test construit dans des configurations avec une seule courbe, un échange de clé, un hachage, un chiffre ou un pkalg activé.tests/scripts/all.sh exécute une combinaison des tests ci-dessus, ainsi que d'autres, avec diverses options de construction (telles que ASan, full mbedtls_config.h , etc.).Au lieu d'installer manuellement les versions requises de tous les outils requis pour les tests, il est possible d'utiliser les images Docker de nos systèmes CI, comme expliqué dans notre référentiel d'infrastructure de test.
Mbed TLS peut être porté sur de nombreuses architectures, systèmes d'exploitation et plates-formes différents. Avant de démarrer un portage, les articles suivants de la base de connaissances peuvent vous être utiles :
Mbed TLS est principalement écrit en C99 portable ; cependant, il présente quelques exigences de plate-forme qui vont au-delà de la norme, mais sont satisfaites par la plupart des architectures modernes :
int et size_t doivent avoir une largeur d'au moins 32 bits.uint8_t , uint16_t , uint32_t et leurs équivalents signés doivent être disponibles.L'architecture de sécurité de la plate-forme (PSA) d'Arm est un ensemble holistique de modèles de menaces, d'analyses de sécurité, de spécifications d'architecture matérielle et micrologicielle et d'une implémentation de référence de micrologiciel open source. PSA fournit une recette, basée sur les meilleures pratiques de l'industrie, qui permet une conception cohérente de la sécurité, tant au niveau du matériel que du micrologiciel.
L'API de cryptographie PSA donne accès à un ensemble de primitives cryptographiques. Son objectif est double. Premièrement, il peut être utilisé dans une plate-forme compatible PSA pour créer des services, tels que le démarrage sécurisé, le stockage sécurisé et la communication sécurisée. Deuxièmement, il peut également être utilisé indépendamment des autres composants PSA sur n’importe quelle plateforme.
Les objectifs de conception de l'API de cryptographie PSA incluent :
Arm accueille favorablement vos commentaires sur la conception de l'API. Si vous pensez que quelque chose pourrait être amélioré, veuillez ouvrir un ticket sur notre référentiel Github. Alternativement, si vous préférez fournir vos commentaires en privé, veuillez nous envoyer un e-mail à [email protected] . Tous les commentaires reçus par e-mail sont traités de manière confidentielle.
Mbed TLS inclut une implémentation de référence de l'API de cryptographie PSA. Cependant, il ne vise pas à implémenter l’intégralité de la spécification ; en particulier il n'implémente pas tous les algorithmes.
Le code X.509 et TLS peut utiliser la cryptographie PSA pour la plupart des opérations. Pour activer cette prise en charge, activez l'option de compilation MBEDTLS_USE_PSA_CRYPTO dans mbedtls_config.h . Notez que TLS 1.3 utilise la cryptographie PSA pour la plupart des opérations, quelle que soit cette option. Voir docs/use-psa-crypto.md pour plus de détails.
Mbed TLS prend en charge les pilotes pour les accélérateurs cryptographiques, les éléments sécurisés et les générateurs aléatoires. C'est un travail en cours. Veuillez noter que les interfaces des pilotes ne sont pas encore totalement stables et peuvent changer sans préavis. Nous avons l'intention de préserver la compatibilité descendante pour le code de l'application (en utilisant l'API PSA Crypto), mais le code des pilotes devra peut-être changer dans les futures versions mineures de Mbed TLS.
Veuillez consulter l'exemple de pilote PSA et le guide pour plus d'informations sur l'écriture d'un pilote.
Lorsque vous utilisez des pilotes, vous souhaiterez généralement activer deux options de compilation (voir le manuel de référence pour plus d'informations) :
MBEDTLS_USE_PSA_CRYPTO est nécessaire pour que le code X.509 et TLS appelle les pilotes PSA plutôt que l'implémentation logicielle intégrée.MBEDTLS_PSA_CRYPTO_CONFIG vous permet d'activer les mécanismes cryptographiques PSA sans inclure le code de l'implémentation logicielle correspondante. Ceci n’est pas encore pris en charge pour tous les mécanismes. Sauf indication contraire spécifique dans un fichier, les fichiers Mbed TLS sont fournis sous une double licence Apache-2.0 OU GPL-2.0 ou version ultérieure. Consultez le fichier LICENSE pour le texte intégral de ces licences, et la section « Licence et droit d'auteur » dans les directives de contribution pour plus d'informations.
Ce projet contient du code provenant d'autres projets. Ce code se trouve dans le répertoire tf-psa-crypto/drivers/ . Le texte de la licence originale est inclus dans les sous-répertoires du projet, là où il diffère de la licence Mbed TLS normale, et/ou dans les fichiers sources. Les projets sont listés ci-dessous :
drivers/everest/ : Les fichiers sont issus du Projet Everest et sont distribués sous la licence Apache 2.0.drivers/p256-m/p256-m/ : Les fichiers ont été extraits du référentiel p256-m. Le code du référentiel d'origine est distribué sous la licence Apache 2.0. Il est distribué en Mbed TLS sous une double licence Apache-2.0 OU GPL-2.0 ou version ultérieure avec l'autorisation de l'auteur. Nous acceptons avec gratitude les rapports de bogues et les contributions de la communauté. Veuillez consulter les directives de contribution pour plus de détails sur la façon de procéder.
SECURITY.md .SUPPORT.md pour d'autres canaux de discussion et d'assistance sur Mbed TLS.
