mbedtls
Mbed TLS 3.6.2
Mbed TLS 是一個 C 函式庫，可實現加密原語、X.509 憑證操作以及 SSL/TLS 和 DTLS 協定。其程式碼佔用空間小，使其適合嵌入式系統。
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 取得。
GitHub 上提供了 PSA 加密 API 的文檔。
若要產生 HTML 格式的庫文檔的本機副本（根據您的編譯時配置自訂）：
make apidoc 。apidoc/index.html或apidoc/modules.html 。有關其他文件來源，請參閱支援文件。
目前，Mbed TLS 版本中使用了三個活躍的建置系統：
用於開發的主要係統是CMake和GNU Make。這些系統始終是完整且最新的。其他應該反映 CMake 和 Make 建置系統中存在的所有更改，儘管功能可能不會自動移植到那裡。
Make 和 CMake 建置系統建立三個函式庫：libmbedcrypto/libtfpsacrypto、libmbedx509 和 libmbedtls。請注意，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
python而不是python3 。若要在系統範圍內安裝軟體包，請省略--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 工具。
我們有意只在 makefile 中使用最少的功能，以使它們盡可能簡單並獨立於不同的工具鏈，從而允許用戶更輕鬆地在不同平台之間移動。需要更多功能的使用者建議使用CMake。
為了使用 GNU Make 從原始碼構建，只需在命令列中輸入：
make
為了運行測試，請輸入：
make check
測試需要建立 Python 並運行 Perl。如果您沒有安裝其中之一，您可以使用以下命令跳過建置測試：
make no_test
您仍然可以使用以下命令執行一組小得多的測試：
programs/test/selftest
為了針對 Windows 平台進行構建，如果目標是 Windows 但構建環境是類 Unix 的（例如交叉編譯或從 MSYS shell 編譯時），則應使用 WINDOWS_BUILD=1；如果目標是 Windows，則應使用WINDOWS=1 WINDOWS_BUILD=1構建環境是Windows shell（例如使用mingw32-make）（在這種情況下某些目標將不可用）。
在您的環境中設定變數SHARED將在靜態庫之外建立共用庫。設定DEBUG將為您提供調試版本。您可以透過在您的環境中或在 make 命令列中設定來覆蓋CFLAGS和LDFLAGS ；可以使用WARNING_CFLAGS單獨覆寫編譯器警告選項。一些特定於目錄的選項（例如， -I指令）仍然保留。
請注意，設定CFLAGS會覆寫其預設值-O2 ，設定WARNING_CFLAGS會覆寫其預設值（以-Wall -Wextra開頭），因此如果您只想在預設選項中新增一些警告選項，可以透過設定CFLAGS=-O2 -Werror例如。當您想要刪除其預設內容時（例如，因為您的編譯器不接受-Wall作為選項），設定WARNING_CFLAGS非常有用。無法從命令列覆蓋特定於目錄的選項。
根據您的平台，您可能會遇到一些問題。請檢查library/ 、 programs/和tests/中的Makefiles以取得針對特定平台手動新增或刪除的選項。您也可以查看 Mbed TLS 知識庫，以了解有關您的平台或問題的文章。
如果您發現還需要執行其他操作，請告知我們具體內容，以便我們將其新增至 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 來檢測程式碼以檢查記憶體錯誤。 （這包括 LeakSanitizer，以及最新版本的 gcc 和 clang。）（使用最新版本的 clang，此模式也使用 UndefinedSanitizer 來檢測程式碼以檢查未定義的行為。）ASanDbg 。與 ASan 相同，但速度較慢，具有調試資訊和更好的堆疊追蹤。MemSan 。這會使用 MemorySanitizer 來偵測程式碼以檢查未初始化的記憶體讀取。實驗性的，需要 Linux/x86_64 上的最新 clang。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/中包含一個精心設計的測試套件，最初需要Python 來產生測試檔案（例如test_suite_ssl.c ）。這些檔案是從function file （例如suites/test_suite_ssl.function ）和data file （例如suites/test_suite_ssl.data ）產生的。 function file包含測試函數。 data file包含測試案例，指定為將傳遞給測試函數的參數。
對於安裝了 Unix shell 和 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 可以移植到許多不同的架構、作業系統和平台。在開始移植之前，您可能會發現以下知識庫文章很有用：
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 驅動程式範例和指南。
使用驅動程式時，您通常需要啟用兩個編譯選項（有關更多信息，請參閱參考手冊）：
MBEDTLS_USE_PSA_CRYPTO是必需的，以便 X.509 和 TLS 程式碼呼叫 PSA 驅動程式而不是內建軟體實作。MBEDTLS_PSA_CRYPTO_CONFIG可讓您啟用 PSA 加密機制，而無需包含對應軟體實作的程式碼。並非所有機制都支援這一點。 除非文件中另有明確說明，否則 mbed TLS 檔案是在 Apache-2.0 或 GPL-2.0 或更高版本雙重授權下提供的。請參閱許可證文件以取得這些許可證的全文，並參閱貢獻指南中的「許可證和版權」部分以取得更多資訊。
該項目包含來自其他項目的程式碼。此程式碼位於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以了解有關 Mbed TLS 的討論和支援的其他管道。
