mbedtls
Mbed TLS 3.6.2
Mbed TLS は、暗号化プリミティブ、X.509 証明書操作、SSL/TLS および DTLS プロトコルを実装する C ライブラリです。コードのフットプリントが小さいため、組み込みシステムに適しています。
Mbed TLS には、PSA 暗号化 API のリファレンス実装が含まれています。これは現在、評価のみを目的としたプレビューです。
Mbed TLS は、ほとんどのシステムですぐに構築できるはずです。一部のプラットフォーム固有のオプションは、完全に文書化された構成ファイルinclude/mbedtls/mbedtls_config.hで使用できます。ここで機能を選択することもできます。このファイルは手動で編集することも、Python 3 スクリプトscripts/config.py使用してよりプログラム的な方法で編集することもできます (使用方法については--helpを使用してください)。
Make および CMake ビルド システムを使用する場合は、 CCやCFLAGSなどの従来の環境変数を使用してコンパイラ オプションを設定できます (下記を参照)。
特定の使用例に焦点を当てたいくつかの非標準構成をconfigs/ディレクトリに提供します。詳細については、 configs/README.txtを参照してください。
主要な Mbed TLS ドキュメントは ReadTheDocs から入手できます。
PSA 暗号化 API のドキュメントは GitHub で入手できます。
コンパイル時の構成に合わせてライブラリ ドキュメントのローカル コピーを HTML 形式で生成するには、次の手順を実行します。
make apidoc実行します。apidoc/index.htmlまたはapidoc/modules.htmlを参照します。他のドキュメントのソースについては、SUPPORT ドキュメントを参照してください。
現在、Mbed TLS リリース内で使用されているアクティブなビルド システムが 3 つあります。
開発に使用される主なシステムは CMake と GNU Make です。これらのシステムは常に完全で最新です。他のものは、CMake および Make ビルド システムに存在するすべての変更を反映する必要がありますが、機能はそこに自動的に移植されない場合があります。
Make および CMake ビルド システムは、libmbedcrypto/libtfpsacrypto、libmbedx509、および libmbedtls の 3 つのライブラリを作成します。 libmbedtls は libmbedx509 および libmbedcrypto/libtfpsacrypto に依存し、libmbedx509 は libmbedcrypto/libtfpsacrypto に依存することに注意してください。その結果、一部のリンカーはフラグが特定の順序であることを期待します。たとえば、GNU リンカーは-lmbedtls -lmbedx509 -lmbedcrypto必要とします。
提供された Makefile を使用してライブラリをビルドするには、次のツールが必要です。
Mbed TLS のdevelopmentブランチとmbedtls-3.6長期サポート ブランチは、Git サブモジュール (フレームワーク) を使用します。これは、単にリリース タグでライブラリをコンパイルする場合には必要ありません。これは、リリース アーカイブ (zip または tar) を使用する場合には必要ありません。
Mbed TLS のソース コードには、スクリプトによって自動的に生成されるいくつかのファイルが含まれており、その内容はプラットフォームやライブラリ構成ではなく、Mbed TLS ソースのみに依存します。これらのファイルは Mbed TLS の開発ブランチには含まれていませんが、生成されたファイルは正式リリースに含まれています。このセクションでは、開発ブランチで不足しているファイルを生成する方法について説明します。
次のツールが必要です。
python3 -m pip install --user -r scripts/basic.requirements.txt
python3代わりにpython呼び出す必要がある場合があります。パッケージをシステム全体にインストールするには、 --userオプションを省略します。クロスコンパイルを行う場合は、構成に依存しないファイルを生成するときに、 CC環境変数をホスト プラットフォームの C コンパイラに設定する必要があります。
構成に依存しないファイルを生成するには、次のいずれかの方法を使用できます。
make実行するか、単にmake実行すると、必要なファイルが自動的に生成されます。make generated_files実行して、構成に依存しないすべてのファイルを生成します。tests/scripts/check-generated-files.sh -u実行して、構成に依存しないファイルをすべて生成します。scriptsmake_generated_files.batを実行して、構成に依存しないすべてのファイルを生成します。GNU Make が必要です。ライブラリとサンプル プログラムをビルドするには、GNU Make と C コンパイラで十分です。より高度なビルド ターゲットの一部には、いくつかの Unix/Linux ツールが必要です。
メイクファイルを可能な限りシンプルにし、さまざまなツールチェーンから独立させ、ユーザーが異なるプラットフォーム間をより簡単に移動できるようにするために、メイクファイルでは意図的に最小限の機能のみを使用します。より多くの機能が必要なユーザーには、CMake の使用をお勧めします。
GNU Make を使用してソース コードからビルドするには、コマンド ラインに次のように入力するだけです。
make
テストを実行するには、次のように入力します。
make check
テストには Python を構築し、Perl を実行する必要があります。いずれもインストールされていない場合は、次のようにしてテストのビルドをスキップできます。
make no_test
以下を使用して、はるかに小規模なテスト セットを実行できます。
programs/test/selftest
Windows プラットフォーム用にビルドするには、ターゲットが Windows であってもビルド環境が Unix 風の場合 (クロスコンパイルまたは MSYS シェルからコンパイルする場合など) にはWINDOWS=1 WINDOWS_BUILD=1を使用し、ビルド環境は Windows シェル (たとえば、mingw32-make を使用) です (その場合、一部のターゲットは使用できません)。
環境で変数SHARED設定すると、静的ライブラリに加えて共有ライブラリが構築されます。 DEBUG設定すると、デバッグ ビルドが提供されます。 CFLAGSとLDFLAGS 、環境内または make コマンド ラインで設定することでオーバーライドできます。コンパイラ警告オプションは、 WARNING_CFLAGSを使用して個別にオーバーライドできます。一部のディレクトリ固有のオプション ( -Iディレクティブなど) は引き続き保持されます。
CFLAGS設定するとデフォルト値の-O2がオーバーライドされ、 WARNING_CFLAGS設定するとデフォルト値 ( -Wall -Wextraで始まる) がオーバーライドされることに注意してください。そのため、デフォルトのオプションにいくつかの警告オプションを追加したいだけの場合は、 CFLAGS=-O2 -Werror設定することで追加できます。 CFLAGS=-O2 -Werrorなど。 WARNING_CFLAGSの設定は、デフォルトの内容を削除したい場合に役立ちます (たとえば、コンパイラーが-Wallオプションとして受け入れないため)。ディレクトリ固有のオプションはコマンド ラインからオーバーライドできません。
プラットフォームによっては、いくつかの問題が発生する可能性があります。特定のプラットフォームに対して手動で追加または削除するオプションについては、 library/ 、 programs/およびtests/の Makefile を確認してください。 Mbed TLS Knowledge Base で、お使いのプラットフォームや問題に関する記事を確認することもできます。
他にも何かを行う必要があることがわかった場合は、その内容をお知らせください。Mbed TLS ナレッジ ベースに追加できます。
別のディレクトリで CMake を使用してソースをビルドするには (推奨)、コマンド ラインに次のように入力します。
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
テストを実行するには、次のように入力します。
ctest
テスト スイートを構築するには Python が必要で、Perl を実行する必要があります。これらのいずれもインストールされていない場合は、次のコマンドを使用してテスト スイートを無効にすることをお勧めします。
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
テスト スイートを無効にし、プログラムを有効にしたままにしても、次のコマンドを使用して、より小規模なテスト セットを実行できます。
programs/test/selftest
共有ライブラリを構築するために CMake を構成するには、次を使用します。
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
CMake ビルドシステム内では、さまざまなビルド モードを使用できます。それらのほとんどは gcc と Clang で利用できますが、一部はコンパイラ固有のものもあります。
Release 。これにより、バイナリ ファイルに不要な情報が含まれないデフォルトのコードが生成されます。Debug 。これによりデバッグ情報が生成され、コードの最適化が無効になります。Coverage 。これにより、デバッグ情報に加えてコード カバレッジ情報も生成されます。ASan 。これにより、AddressSanitizer がコードに組み込まれ、メモリ エラーがチェックされます。 (これには、gcc と Clang の最新バージョンを使用した LeakSanitizer が含まれます。) (Clang の最新バージョンでは、このモードは、未定義の動作をチェックするために、UnknownSanitizer を使用してコードをインストルメント化します。)ASanDbg 。 ASan と同じですが、速度が遅く、デバッグ情報とスタック トレースが向上しています。MemSan 。これにより、コードに MemorySanitizer が組み込まれ、初期化されていないメモリ読み取りがチェックされます。実験的で、Linux/x86_64 上で最新のクランが必要です。MemSanDbg 。 MemSan と同じですが、速度が遅く、デバッグ情報があり、スタック トレースとオリジン トラッキングが改善されています。Check 。これにより、最適化に依存するコンパイラ警告がアクティブになり、すべての警告がエラーとして扱われます。CMake でのビルド モードの切り替えは簡単です。デバッグ モードの場合は、コマンド ラインに次のように入力します。
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
他の利用可能な CMake オプションをリストするには、次を使用します。
cmake -LH
CMake では、cmake の最初の呼び出し後にコンパイラーやそのフラグを調整できないことに注意してください。これは、 CC=your_cc makeとmake CC=your_cc機能しないことを意味します ( CFLAGSや他の変数と同様)。これらの変数は、初めて cmake を呼び出すときに調整する必要があります。次に例を示します。
CC=your_cc cmake /path/to/mbedtls_source
すでに cmake を呼び出しており、それらの設定を変更したい場合は、ビルド ディレクトリを削除して、再度作成する必要があります。
インプレースで構築することも可能であることに注意してください。ただし、これにより、提供された Makefile が上書きされます ( git statusで変更済みとして表示されないようにする場合は、 scripts/tmp_ignore_makefiles.sh参照してください)。これを行うには、Mbed TLS ソース ディレクトリから次を使用します。
cmake .
make
後でCCまたはCFLAGS変更する場合は、CMake キャッシュを削除する必要があります。これは、GNU find を使用して次のコマンドで実行できます。
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
これで、必要な変更を加えることができます。
CC=your_cc cmake .
make
変数に関しては、cmake の呼び出し時に CFLAGS を設定した場合、CFLAGS の値は cmake によって提供される内容をオーバーライドせず (上記のビルド モードに応じて)、単に先頭に追加されるだけであることにも注意してください。
Mbed TLS は、他の CMake プロジェクトで依存関係として使用できるパッケージ構成ファイルを提供します。次のようにして、Mbed TLS の CMake ターゲットを自分で含めることができます。
find_package(MbedTLS)
プロンプトが表示されたら、 MbedTLS_DIR ${YOUR_MBEDTLS_INSTALL_DIR}/cmakeに設定します。これにより、次のターゲットが作成されます。
MbedTLS::tfpsacrypto (暗号ライブラリ)MbedTLS::mbedtls (TLS ライブラリ)MbedTLS::mbedx509 (X509 ライブラリ)これらは、 target_link_libraries()を通じて直接使用できます。
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
これにより、Mbed TLS ライブラリがライブラリまたはアプリケーションにリンクされ、そのインクルード ディレクトリがターゲットに追加されます ( PUBLICまたはINTERFACEリンク ライブラリの場合は推移的に)。
Mbed TLS は、CMake サブプロジェクトとしてのビルドをサポートしています。親 CMake プロジェクトからadd_subdirectory()使用して、Mbed TLS をサブプロジェクトとして含めることができます。
Microsoft Visual Studio のビルド ファイルは、Visual Studio 2017 用に生成されます。
ソリューション ファイルmbedTLS.slnには、ライブラリとすべてのプログラムを構築するために必要なすべての基本プロジェクトが含まれています。テスト内のファイルは、Python および Perl 環境も必要とするため、生成およびコンパイルされません。ただし、 programs/test/にあるセルフテスト プログラムは引き続き使用できます。
Mbed TLS の開発ブランチでは、「開発ブランチで生成されるソース ファイル」で説明されているように、最初に Visual Studio ソリューション ファイルを生成する必要があります。
さまざまな機能と使用法のためのサンプル プログラムが、 programs/に含まれています。これらのサンプル プログラムの目的はライブラリの特定の機能をデモンストレーションすることであり、実際のアプリケーションを構築するにはコードを調整する必要がある場合があることに注意してください。
Mbed TLS には、 tests/に精巧なテスト スイートが含まれており、最初にテスト ファイル (例: test_suite_ssl.c ) を生成するために Python が必要です。これらのファイルはfunction file (例: suites/test_suite_ssl.function ) およびdata file (例: suites/test_suite_ssl.data ) から生成されます。 function fileテスト関数が含まれています。 data file 、テスト関数に渡されるパラメーターとして指定されたテスト ケースが含まれています。
Unix シェルと OpenSSL (およびオプションで GnuTLS) がインストールされているマシンの場合は、追加のテスト スクリプトを使用できます。
tests/ssl-opt.shさまざまな TLS オプション (再ネゴシエーション、再開など) の統合テストを実行し、これらのオプションと他の実装との相互運用性をテストします。tests/compat.shすべての暗号スイートと他の実装との相互運用性をテストします。tests/scripts/test-ref-configs.plテストは、さまざまな縮小構成でビルドされます。tests/scripts/depends.pyテストは、単一曲線、キー交換、ハッシュ、暗号、または pkalg をオンにした構成でビルドされます。tests/scripts/all.sh 、上記のテストに加えて、さまざまなビルド オプション (ASan、完全なmbedtls_config.hなど) を組み合わせて実行します。テスト インフラストラクチャ リポジトリで説明されているように、テストに必要なすべてのツールの必要なバージョンを手動でインストールする代わりに、CI システムの Docker イメージを使用することができます。
Mbed TLS は、さまざまなアーキテクチャ、OS、プラットフォームに移植できます。移植を開始する前に、次のナレッジベースの記事が役立つ場合があります。
Mbed TLS はほとんどが移植可能な C99 で書かれています。ただし、標準を超えるプラットフォーム要件がいくつかありますが、最新のアーキテクチャのほとんどは満たしています。
intとsize_t少なくとも 32 ビット幅でなければなりません。uint8_t 、 uint16_t 、 uint32_t型、およびそれらの符号付き同等の型が使用可能である必要があります。Arm のプラットフォーム セキュリティ アーキテクチャ (PSA) は、脅威モデル、セキュリティ分析、ハードウェアとファームウェアのアーキテクチャ仕様、およびオープンソース ファームウェアのリファレンス実装の総合的なセットです。 PSA は、業界のベスト プラクティスに基づいて、ハードウェア レベルとファームウェア レベルの両方でセキュリティを一貫して設計できるようにするレシピを提供します。
PSA 暗号化 API は、一連の暗号化プリミティブへのアクセスを提供します。これには二重の目的があります。まず、PSA 準拠のプラットフォームで使用して、セキュア ブート、セキュア ストレージ、セキュアな通信などのサービスを構築できます。次に、任意のプラットフォーム上で他の PSA コンポーネントから独立して使用することもできます。
PSA 暗号化 API の設計目標には次が含まれます。
Arm は API の設計に関するフィードバックを歓迎します。何かを改善できると思われる場合は、Github リポジトリでイシューを開いてください。あるいは、フィードバックを非公開で提供したい場合は、 [email protected]までメールでお問い合わせください。電子メールで受け取ったすべてのフィードバックは機密として扱われます。
Mbed TLS には、PSA 暗号化 API のリファレンス実装が含まれています。ただし、仕様全体を実装することを目的としたものではありません。特に、すべてのアルゴリズムが実装されているわけではありません。
X.509 および TLS コードでは、ほとんどの操作に PSA 暗号化を使用できます。このサポートを有効にするには、 mbedtls_config.hのコンパイル オプションMBEDTLS_USE_PSA_CRYPTOを有効にします。 TLS 1.3 では、このオプションに関係なく、ほとんどの操作で PSA 暗号化が使用されることに注意してください。詳細については、 docs/use-psa-crypto.mdを参照してください。
Mbed TLS は、暗号化アクセラレータ、セキュア エレメント、ランダム ジェネレーターのドライバーをサポートしています。これは進行中の作業です。ドライバー インターフェイスはまだ完全に安定していないため、予告なく変更される可能性があることに注意してください。アプリケーション コード (PSA Crypto API を使用) の下位互換性を維持するつもりですが、Mbed TLS の将来のマイナー リリースではドライバーのコードを変更する必要がある可能性があります。
ドライバーの作成については、PSA ドライバーのサンプルとガイドを参照してください。
ドライバーを使用するときは、通常、2 つのコンパイル オプションを有効にする必要があります (詳細については、リファレンス マニュアルを参照してください)。
MBEDTLS_USE_PSA_CRYPTO 、X.509 および TLS コードが組み込みソフトウェア実装ではなく PSA ドライバーを呼び出すようにするために必要です。MBEDTLS_PSA_CRYPTO_CONFIG使用すると、対応するソフトウェア実装のコードを含めずに PSA 暗号化メカニズムを有効にすることができます。これはまだすべてのメカニズムでサポートされているわけではありません。 ファイル内で特に指定されていない限り、Mbed TLS ファイルはデュアル Apache-2.0 または GPL-2.0 以降のライセンスに基づいて提供されます。これらのライセンスの全文については LICENSE ファイルを、詳細については貢献ガイドラインの「ライセンスと著作権」セクションを参照してください。
このプロジェクトには他のプロジェクトのコードが含まれています。このコードはtf-psa-crypto/drivers/ディレクトリ内にあります。元のライセンス テキストはプロジェクトのサブディレクトリ内に含まれており、通常の Mbed TLS ライセンスやソース ファイルとは異なります。プロジェクトは以下のとおりです。
drivers/everest/ : ファイルは Project Everest から派生し、Apache 2.0 ライセンスに基づいて配布されます。drivers/p256-m/p256-m/ : ファイルは p256-m リポジトリから取得されました。元のリポジトリのコードは、Apache 2.0 ライセンスに基づいて配布されます。これは、作者の許可を得て、Apache-2.0 または GPL-2.0 以降のデュアル ライセンスに基づいて Mbed TLS で配布されます。 コミュニティからのバグレポートや貢献をありがたく受け入れます。これを行う方法の詳細については、投稿ガイドラインを参照してください。
SECURITY.mdを参照してください。SUPPORT.md参照してください。
