mbedtls
Mbed TLS 3.6.2
Mbed TLS ist eine C-Bibliothek, die kryptografische Grundelemente, X.509-Zertifikatsmanipulation und die Protokolle SSL/TLS und DTLS implementiert. Aufgrund seines geringen Code-Footprints eignet es sich für eingebettete Systeme.
Mbed TLS enthält eine Referenzimplementierung der PSA-Kryptographie-API. Dies ist derzeit nur eine Vorschau zu Evaluierungszwecken.
Mbed TLS sollte auf den meisten Systemen sofort einsatzbereit sein. Einige plattformspezifische Optionen sind in der vollständig dokumentierten Konfigurationsdatei include/mbedtls/mbedtls_config.h verfügbar. Dort können auch Funktionen ausgewählt werden. Diese Datei kann manuell oder programmgesteuert mit dem Python 3-Skript scripts/config.py bearbeitet werden (verwenden Sie --help für Anweisungen zur Verwendung).
Compiler-Optionen können mithilfe herkömmlicher Umgebungsvariablen wie CC und CFLAGS festgelegt werden, wenn das Make- und CMake-Build-System verwendet wird (siehe unten).
Wir stellen einige nicht standardmäßige Konfigurationen zur Verfügung, die sich auf bestimmte Anwendungsfälle im Verzeichnis configs/ konzentrieren. Weitere Informationen hierzu finden Sie in configs/README.txt
Die Hauptdokumentation zu Mbed TLS ist über ReadTheDocs verfügbar.
Die Dokumentation für die PSA-Kryptographie-API ist auf GitHub verfügbar.
So generieren Sie eine lokale Kopie der Bibliotheksdokumentation im HTML-Format, zugeschnitten auf Ihre Konfiguration zur Kompilierungszeit:
make apidoc aus.apidoc/index.html oder apidoc/modules.html .Weitere Dokumentationsquellen finden Sie im SUPPORT-Dokument.
Derzeit werden in Mbed TLS-Releases drei aktive Build-Systeme verwendet:
Die für die Entwicklung hauptsächlich verwendeten Systeme sind CMake und GNU Make. Diese Systeme sind stets vollständig und aktuell. Die anderen sollten alle im CMake- und Make-Build-System vorhandenen Änderungen widerspiegeln, obwohl Funktionen möglicherweise nicht automatisch dorthin portiert werden.
Die Build-Systeme Make und CMake erstellen drei Bibliotheken: libmbedcrypto/libtfpsacrypto, libmbedx509 und libmbedtls. Beachten Sie, dass libmbedtls von libmbedx509 und libmbedcrypto/libtfpsacrypto abhängt und libmbedx509 von libmbedcrypto/libtfpsacrypto abhängt. Daher erwarten einige Linker, dass sich die Flags in einer bestimmten Reihenfolge befinden, beispielsweise möchte der GNU-Linker -lmbedtls -lmbedx509 -lmbedcrypto .
Sie benötigen die folgenden Tools, um die Bibliothek mit den bereitgestellten Makefiles zu erstellen:
Der development und der mbedtls-3.6 Langzeitunterstützungszweig von Mbed TLS verwenden ein Git-Submodul (Framework). Dies ist nicht erforderlich, um die Bibliothek lediglich mit einem Release-Tag zu kompilieren. Dies ist nicht erforderlich, um ein Release-Archiv (zip oder tar) zu nutzen.
Der Quellcode von Mbed TLS enthält einige Dateien, die automatisch von Skripten generiert werden und deren Inhalt nur von der Mbed TLS-Quelle abhängt, nicht von der Plattform oder der Bibliothekskonfiguration. Diese Dateien sind nicht im Entwicklungszweig von Mbed TLS enthalten, die generierten Dateien sind jedoch in offiziellen Versionen enthalten. In diesem Abschnitt wird erläutert, wie die fehlenden Dateien im Entwicklungszweig generiert werden.
Folgende Werkzeuge werden benötigt:
python3 -m pip install --user -r scripts/basic.requirements.txt
python anstelle von python3 aufrufen. Um die Pakete systemweit zu installieren, lassen Sie die Option --user weg. Wenn Sie eine Kreuzkompilierung durchführen, müssen Sie beim Generieren der konfigurationsunabhängigen Dateien die CC Umgebungsvariable auf einen C-Compiler für die Hostplattform festlegen.
Zum Generieren der konfigurationsunabhängigen Dateien stehen folgende Methoden zur Verfügung:
make mit einem beliebigen Ziel oder einfach nur make die erforderlichen Dateien automatisch generiert.make generated_files aus, um alle konfigurationsunabhängigen Dateien zu generieren.tests/scripts/check-generated-files.sh -u aus, um alle konfigurationsunabhängigen Dateien zu generieren.scriptsmake_generated_files.bat aus, um alle konfigurationsunabhängigen Dateien zu generieren.Wir benötigen GNU Make. Zum Erstellen der Bibliothek und der Beispielprogramme genügen GNU Make und ein C-Compiler. Einige der fortgeschritteneren Build-Ziele erfordern einige Unix/Linux-Tools.
Wir verwenden in den Makefiles bewusst nur ein Minimum an Funktionalität, um sie so einfach und unabhängig von verschiedenen Toolchains wie möglich zu halten und Benutzern einen einfacheren Wechsel zwischen verschiedenen Plattformen zu ermöglichen. Benutzern, die mehr Funktionen benötigen, wird die Verwendung von CMake empfohlen.
Um mit GNU Make aus dem Quellcode zu erstellen, geben Sie einfach in die Befehlszeile ein:
make
Um die Tests auszuführen, geben Sie Folgendes ein:
make check
Für die Tests muss Python erstellt und Perl ausgeführt werden. Wenn Sie keines davon installiert haben, können Sie die Erstellung der Tests überspringen mit:
make no_test
Sie können immer noch eine viel kleinere Reihe von Tests ausführen mit:
programs/test/selftest
Um für eine Windows-Plattform zu erstellen, sollten Sie WINDOWS_BUILD=1 verwenden, wenn das Ziel Windows ist, die Build-Umgebung jedoch Unix-ähnlich ist (z. B. beim Cross-Compilieren oder Kompilieren aus einer MSYS-Shell), und WINDOWS=1 , wenn dies der Fall ist Die Build-Umgebung ist eine Windows-Shell (z. B. mit mingw32-make) (in diesem Fall sind einige Ziele nicht verfügbar).
Wenn Sie in Ihrer Umgebung die Variable SHARED festlegen, werden zusätzlich zu den statischen Bibliotheken auch gemeinsam genutzte Bibliotheken erstellt. Wenn Sie DEBUG festlegen, erhalten Sie einen Debug-Build. Sie können CFLAGS und LDFLAGS überschreiben, indem Sie sie in Ihrer Umgebung oder in der Make-Befehlszeile festlegen. Compiler-Warnoptionen können separat mit WARNING_CFLAGS überschrieben werden. Einige verzeichnisspezifische Optionen (z. B. -I -Anweisungen) bleiben weiterhin erhalten.
Bitte beachten Sie, dass die Einstellung CFLAGS den Standardwert -O2 und die Einstellung WARNING_CFLAGS den Standardwert überschreibt (beginnend mit -Wall -Wextra ). Wenn Sie also nur einige Warnoptionen zu den Standardoptionen hinzufügen möchten, können Sie dies tun, indem Sie CFLAGS=-O2 -Werror festlegen CFLAGS=-O2 -Werror zum Beispiel. Das Festlegen WARNING_CFLAGS ist nützlich, wenn Sie den Standardinhalt entfernen möchten (z. B. weil Ihr Compiler -Wall nicht als Option akzeptiert). Verzeichnisspezifische Optionen können nicht über die Befehlszeile überschrieben werden.
Abhängig von Ihrer Plattform können einige Probleme auftreten. Bitte überprüfen Sie die Makefiles in library/ , programs/ und tests/ auf Optionen zum manuellen Hinzufügen oder Entfernen für bestimmte Plattformen. Sie können auch in der Mbed TLS Knowledge Base nach Artikeln zu Ihrer Plattform oder Ihrem Problem suchen.
Falls Sie feststellen, dass Sie noch etwas anderes tun müssen, teilen Sie uns dies bitte mit, damit wir es zur Mbed TLS-Wissensdatenbank hinzufügen können.
Um die Quelle mit CMake in einem separaten Verzeichnis zu erstellen (empfohlen), geben Sie einfach in die Befehlszeile ein:
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
Um die Tests auszuführen, geben Sie Folgendes ein:
ctest
Für die Testsuiten muss Python erstellt und Perl ausgeführt werden. Wenn Sie keines davon installiert haben, sollten Sie die Testsuiten wie folgt deaktivieren:
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Wenn Sie die Testsuiten deaktiviert, die Programme jedoch aktiviert gelassen haben, können Sie immer noch eine viel kleinere Reihe von Tests ausführen mit:
programs/test/selftest
Um CMake für die Erstellung gemeinsam genutzter Bibliotheken zu konfigurieren, verwenden Sie:
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Im CMake-Buildsystem stehen viele verschiedene Build-Modi zur Verfügung. Die meisten davon sind für gcc und clang verfügbar, einige sind jedoch Compiler-spezifisch:
Release . Dadurch wird der Standardcode ohne unnötige Informationen in den Binärdateien generiert.Debug . Dadurch werden Debug-Informationen generiert und die Optimierung des Codes deaktiviert.Coverage . Dadurch werden zusätzlich zu den Debug-Informationen auch Code-Coverage-Informationen generiert.ASan . Dadurch wird der Code mit AddressSanitizer instrumentiert, um auf Speicherfehler zu prüfen. (Dazu gehört LeakSanitizer mit der neuesten Version von gcc und clang.) (Mit der neuesten Version von clang instrumentiert dieser Modus den Code auch mit UndefinedSanitizer, um auf undefiniertes Verhalten zu prüfen.)ASanDbg . Wie ASan, aber langsamer, mit Debug-Informationen und besseren Stack-Traces.MemSan . Dadurch wird der Code mit MemorySanitizer instrumentiert, um nach nicht initialisierten Speicherlesevorgängen zu suchen. Experimentell, benötigt aktuelles Clang auf Linux/x86_64.MemSanDbg . Wie MemSan, aber langsamer, mit Debug-Informationen, besseren Stack-Traces und Ursprungsverfolgung.Check . Dadurch werden die Compiler-Warnungen aktiviert, die von der Optimierung abhängen, und alle Warnungen werden als Fehler behandelt.Das Wechseln des Build-Modus in CMake ist einfach. Geben Sie für den Debug-Modus in der Befehlszeile Folgendes ein:
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Um andere verfügbare CMake-Optionen aufzulisten, verwenden Sie:
cmake -LH
Beachten Sie, dass Sie mit CMake den Compiler oder seine Flags nach dem ersten Aufruf von cmake nicht mehr anpassen können. Das bedeutet, dass CC=your_cc make und make CC=your_cc nicht funktionieren (ähnlich wie bei CFLAGS und anderen Variablen). Diese Variablen müssen beim ersten Aufruf von cmake angepasst werden, zum Beispiel:
CC=your_cc cmake /path/to/mbedtls_source
Wenn Sie cmake bereits aufgerufen haben und diese Einstellungen ändern möchten, müssen Sie das Build-Verzeichnis entfernen und erneut erstellen.
Beachten Sie, dass es möglich ist, vor Ort zu bauen. Dadurch werden jedoch die bereitgestellten Makefiles überschrieben (siehe scripts/tmp_ignore_makefiles.sh wenn Sie verhindern möchten, dass git status sie als geändert anzeigt). Verwenden Sie dazu aus dem Mbed TLS-Quellverzeichnis Folgendes:
cmake .
make
Wenn Sie CC oder CFLAGS nachträglich ändern möchten, müssen Sie den CMake-Cache entfernen. Dies kann mit dem folgenden Befehl mithilfe von GNU find erfolgen:
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Sie können nun die gewünschte Änderung vornehmen:
CC=your_cc cmake .
make
Beachten Sie in Bezug auf Variablen auch, dass, wenn Sie CFLAGS beim Aufrufen von cmake festlegen, Ihr Wert von CFLAGS den von cmake bereitgestellten Inhalt nicht überschreibt (abhängig vom Build-Modus, wie oben gezeigt), sondern ihm lediglich vorangestellt wird.
Mbed TLS stellt eine Paketkonfigurationsdatei zur Verwendung als Abhängigkeit in anderen CMake-Projekten bereit. Sie können die CMake-Ziele von Mbed TLS selbst einbinden mit:
find_package(MbedTLS)
Wenn Sie dazu aufgefordert werden, legen Sie MbedTLS_DIR auf ${YOUR_MBEDTLS_INSTALL_DIR}/cmake fest. Dadurch entstehen folgende Ziele:
MbedTLS::tfpsacrypto (Kryptobibliothek)MbedTLS::mbedtls (TLS-Bibliothek)MbedTLS::mbedx509 (X509-Bibliothek) Sie können diese dann direkt über target_link_libraries() verwenden:
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
Dadurch werden die Mbed-TLS-Bibliotheken mit Ihrer Bibliothek oder Anwendung verknüpft und deren Include-Verzeichnisse zu Ihrem Ziel hinzugefügt (transitiv, im Fall von PUBLIC oder INTERFACE Linkbibliotheken).
Mbed TLS unterstützt die Erstellung als CMake-Unterprojekt. Man kann add_subdirectory() aus einem übergeordneten CMake-Projekt verwenden, um Mbed TLS als Unterprojekt einzubinden.
Die Builddateien für Microsoft Visual Studio werden für Visual Studio 2017 generiert.
Die Lösungsdatei mbedTLS.sln enthält alle grundlegenden Projekte, die zum Erstellen der Bibliothek und aller Programme erforderlich sind. Die Dateien in Tests werden nicht generiert und kompiliert, da diese auch Python- und Perl-Umgebungen benötigen. Das Selbsttestprogramm unter programs/test/ ist jedoch weiterhin verfügbar.
Im Entwicklungszweig von Mbed TLS müssen zunächst die Visual Studio-Lösungsdateien generiert werden, wie unter „Generierte Quelldateien im Entwicklungszweig“ beschrieben.
Wir haben Beispielprogramme für viele verschiedene Funktionen und Verwendungszwecke in programs/ eingefügt. Bitte beachten Sie, dass das Ziel dieser Beispielprogramme darin besteht, bestimmte Funktionen der Bibliothek zu demonstrieren, und dass der Code möglicherweise angepasst werden muss, um eine reale Anwendung zu erstellen.
Mbed TLS enthält eine umfangreiche Testsuite in tests/ die zunächst Python zum Generieren der Testdateien erfordert (z. B. test_suite_ssl.c ). Diese Dateien werden aus einer function file (z. B. suites/test_suite_ssl.function ) und einer data file (z. B. suites/test_suite_ssl.data ) generiert. Die function file enthält die Testfunktionen. Die data file enthält die Testfälle, die als Parameter angegeben werden, die an die Testfunktion übergeben werden.
Für Maschinen mit einer Unix-Shell und installiertem OpenSSL (und optional GnuTLS) sind zusätzliche Testskripte verfügbar:
tests/ssl-opt.sh führt Integrationstests für verschiedene TLS-Optionen (Neuverhandlung, Wiederaufnahme usw.) durch und testet die Interoperabilität dieser Optionen mit anderen Implementierungen.tests/compat.sh testet die Interoperabilität jeder Ciphersuite mit anderen Implementierungen.tests/scripts/test-ref-configs.pl Test-Builds in verschiedenen reduzierten Konfigurationen.tests/scripts/depends.py test baut Konfigurationen mit einer einzelnen Kurve, einem Schlüsselaustausch, einem Hash, einer Verschlüsselung oder einem Pkalg ein.tests/scripts/all.sh führt eine Kombination der oben genannten Tests und einige weitere mit verschiedenen Build-Optionen aus (z. B. ASan, vollständiges mbedtls_config.h usw.).Anstatt die erforderlichen Versionen aller zum Testen erforderlichen Tools manuell zu installieren, ist es möglich, die Docker-Images aus unseren CI-Systemen zu verwenden, wie in unserem Testinfrastruktur-Repository erläutert.
Mbed TLS kann auf viele verschiedene Architekturen, Betriebssysteme und Plattformen portiert werden. Bevor Sie mit der Portierung beginnen, könnten die folgenden Knowledge Base-Artikel für Sie hilfreich sein:
Mbed TLS ist größtenteils in portablem C99 geschrieben; Allerdings gibt es einige Plattformanforderungen, die über den Standard hinausgehen, aber von den meisten modernen Architekturen erfüllt werden:
int und size_t müssen mindestens 32 Bit breit sein.uint8_t , uint16_t , uint32_t und ihre vorzeichenbehafteten Äquivalente müssen verfügbar sein.Die Platform Security Architecture (PSA) von Arm ist ein ganzheitlicher Satz von Bedrohungsmodellen, Sicherheitsanalysen, Hardware- und Firmware-Architekturspezifikationen und einer Open-Source-Firmware-Referenzimplementierung. PSA bietet ein Rezept, das auf Best Practices der Branche basiert und eine konsistente Gestaltung der Sicherheit sowohl auf Hardware- als auch auf Firmware-Ebene ermöglicht.
Die PSA-Kryptografie-API bietet Zugriff auf eine Reihe kryptografischer Grundelemente. Es hat einen doppelten Zweck. Erstens kann es in einer PSA-kompatiblen Plattform zum Aufbau von Diensten wie sicherem Booten, sicherer Speicherung und sicherer Kommunikation verwendet werden. Zweitens ist es auch unabhängig von anderen PSA-Komponenten auf jeder Plattform einsetzbar.
Zu den Entwurfszielen der PSA-Kryptografie-API gehören:
Arm freut sich über Rückmeldungen zum Design der API. Wenn Sie der Meinung sind, dass etwas verbessert werden könnte, öffnen Sie bitte ein Problem in unserem Github-Repository. Wenn Sie Ihr Feedback lieber privat abgeben möchten, senden Sie uns alternativ eine E-Mail an [email protected] . Alle per E-Mail eingehenden Rückmeldungen werden vertraulich behandelt.
Mbed TLS enthält eine Referenzimplementierung der PSA-Kryptographie-API. Ziel ist jedoch nicht die Umsetzung der gesamten Spezifikation; insbesondere werden nicht alle Algorithmen implementiert.
Der X.509- und TLS-Code kann für die meisten Vorgänge die PSA-Kryptografie verwenden. Um diese Unterstützung zu aktivieren, aktivieren Sie die Kompilierungsoption MBEDTLS_USE_PSA_CRYPTO in mbedtls_config.h . Beachten Sie, dass TLS 1.3 unabhängig von dieser Option für die meisten Vorgänge PSA-Kryptografie verwendet. Weitere Informationen finden Sie unter docs/use-psa-crypto.md .
Mbed TLS unterstützt Treiber für kryptografische Beschleuniger, sichere Elemente und Zufallsgeneratoren. Dies ist in Arbeit. Bitte beachten Sie, dass die Treiberschnittstellen noch nicht vollständig stabil sind und sich ohne Vorankündigung ändern können. Wir beabsichtigen, die Abwärtskompatibilität für Anwendungscode (mithilfe der PSA Crypto API) zu wahren, der Code der Treiber muss sich jedoch möglicherweise in zukünftigen Nebenversionen von Mbed TLS ändern.
Informationen zum Schreiben eines Treibers finden Sie im PSA-Treiberbeispiel und in der Anleitung.
Bei der Verwendung von Treibern sollten Sie im Allgemeinen zwei Kompilierungsoptionen aktivieren (weitere Informationen finden Sie im Referenzhandbuch):
MBEDTLS_USE_PSA_CRYPTO ist erforderlich, damit der X.509- und TLS-Code die PSA-Treiber und nicht die integrierte Softwareimplementierung aufruft.MBEDTLS_PSA_CRYPTO_CONFIG können Sie kryptografische PSA-Mechanismen aktivieren, ohne den Code der entsprechenden Softwareimplementierung einzubeziehen. Dies wird noch nicht für alle Mechanismen unterstützt. Sofern in einer Datei nicht ausdrücklich anders angegeben, werden Mbed-TLS-Dateien unter einer doppelten Apache-2.0- oder GPL-2.0- oder höher-Lizenz bereitgestellt. Den vollständigen Text dieser Lizenzen finden Sie in der Datei LIZENZ. Weitere Informationen finden Sie im Abschnitt „Lizenz und Urheberrecht“ in den Beitragsrichtlinien.
Dieses Projekt enthält Code aus anderen Projekten. Dieser Code befindet sich im Verzeichnis tf-psa-crypto/drivers/ . Der ursprüngliche Lizenztext ist in Projektunterverzeichnissen enthalten, wo er von der normalen Mbed TLS-Lizenz abweicht, und/oder in Quelldateien. Nachfolgend sind die Projekte aufgeführt:
drivers/everest/ : Dateien stammen aus Project Everest und werden unter der Apache 2.0-Lizenz vertrieben.drivers/p256-m/p256-m/ : Dateien wurden aus dem p256-m-Repository entnommen. Der Code im Original-Repository wird unter der Apache 2.0-Lizenz verteilt. Es wird in Mbed TLS unter einer doppelten Apache-2.0- oder GPL-2.0-oder höher-Lizenz mit Genehmigung des Autors vertrieben. Wir nehmen Fehlerberichte und Beiträge aus der Community dankbar entgegen. Einzelheiten dazu finden Sie in den Beitragsrichtlinien.
SECURITY.md .SUPPORT.md .
