mbedtls
Mbed TLS 3.6.2
Mbed TLS — это библиотека C, которая реализует криптографические примитивы, манипулирование сертификатами X.509 и протоколы SSL/TLS и DTLS. Небольшой размер кода делает его подходящим для встроенных систем.
Mbed TLS включает эталонную реализацию API криптографии PSA. В настоящее время это предварительная версия только для ознакомительных целей.
Mbed TLS должен быть готов к использованию в большинстве систем. Некоторые параметры, специфичные для платформы, доступны в полностью документированном файле конфигурации include/mbedtls/mbedtls_config.h , который также является местом, где можно выбирать функции. Этот файл можно редактировать вручную или более программным способом, используя скрипт Python 3 scripts/config.py (инструкции по использованию используйте --help ).
Параметры компилятора можно задать с помощью обычных переменных среды, таких как CC и CFLAGS при использовании системы сборки Make и CMake (см. ниже).
В каталоге configs/ мы предоставляем некоторые нестандартные конфигурации, ориентированные на конкретные случаи использования. Подробнее о них можно прочитать в configs/README.txt
Основная документация Mbed TLS доступна через ReadTheDocs.
Документация по API криптографии PSA доступна на GitHub.
Чтобы создать локальную копию документации библиотеки в формате 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 .
Для сборки библиотеки с помощью предоставленных make-файлов вам потребуются следующие инструменты:
Ветка development и ветка долгосрочной поддержки mbedtls-3.6 Mbed TLS используют подмодуль (фреймворк) 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.
Мы намеренно используем только минимум функциональности в make-файлах, чтобы сделать их максимально простыми и независимыми от различных наборов инструментов, чтобы пользователи могли легче перемещаться между различными платформами. Пользователям, которым нужны дополнительные функции, рекомендуется использовать CMake.
Чтобы выполнить сборку из исходного кода с помощью GNU Make, просто введите в командной строке:
make
Для запуска тестов введите:
make check
Для тестов необходимо собрать Python и запустить Perl. Если ни один из них у вас не установлен, вы можете пропустить сборку тестов с помощью:
make no_test
Вы по-прежнему сможете запускать гораздо меньший набор тестов с помощью:
programs/test/selftest
Чтобы выполнить сборку для платформы Windows, вам следует использовать WINDOWS_BUILD=1 , если целью является Windows, но среда сборки подобна Unix (например, при кросс-компиляции или компиляции из оболочки MSYS), и WINDOWS=1 если Среда сборки — это оболочка Windows (например, с использованием mingw32-make) (в этом случае некоторые цели будут недоступны).
Установка переменной SHARED в вашей среде приведет к созданию общих библиотек в дополнение к статическим библиотекам. Установка DEBUG дает вам отладочную сборку. Вы можете переопределить CFLAGS и LDFLAGS , установив их в своей среде или в командной строке make; Параметры предупреждения компилятора могут быть переопределены отдельно с помощью WARNING_CFLAGS . Некоторые параметры, специфичные для каталога (например, директивы -I ), по-прежнему сохраняются.
Обратите внимание, что установка CFLAGS переопределяет значение по умолчанию -O2 , а установка WARNING_CFLAGS переопределяет значение по умолчанию (начиная с -Wall -Wextra ), поэтому, если вы просто хотите добавить некоторые параметры предупреждения к настройкам по умолчанию, вы можете сделать это, установив CFLAGS=-O2 -Werror например. Установка WARNING_CFLAGS полезна, когда вы хотите избавиться от содержимого по умолчанию (например, потому, что ваш компилятор не принимает -Wall в качестве опции). Параметры, специфичные для каталога, нельзя переопределить из командной строки.
В зависимости от вашей платформы вы можете столкнуться с некоторыми проблемами. Пожалуйста, проверьте файлы Makefile в library/ , programs/ и tests/ чтобы найти варианты добавления или удаления вручную для определенных платформ. Вы также можете проверить базу знаний 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 этот режим также добавляет в код UndefineSanitizer для проверки неопределенного поведения.)ASanDbg . То же, что и ASan, но медленнее, с отладочной информацией и улучшенной трассировкой стека.MemSan . Это снабжает код MemorySanitizer для проверки неинициализированного чтения памяти. Экспериментальный вариант, требуется недавний clang на 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 (см. scripts/tmp_ignore_makefiles.sh если вы хотите, чтобы git status не показывал их как измененные). Для этого в исходном каталоге Mbed TLS используйте:
cmake .
make
Если вы захотите впоследствии изменить CC или CFLAGS , вам потребуется удалить кеш CMake. Это можно сделать с помощью следующей команды с помощью GNU find:
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Теперь вы можете внести желаемые изменения:
CC=your_cc cmake .
make
Что касается переменных, также обратите внимание, что если вы устанавливаете CFLAGS при вызове cmake, ваше значение CFLAGS не переопределяет содержимое, предоставленное cmake (в зависимости от режима сборки, как показано выше), оно просто добавляется к нему.
Mbed TLS предоставляет файл конфигурации пакета для использования в качестве зависимости в других проектах CMake. Вы можете самостоятельно включить цели CMake Mbed TLS с помощью:
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. Можно использовать add_subdirectory() из родительского проекта CMake, чтобы включить 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 и установленным 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 и т. д.).Вместо ручной установки необходимых версий всех инструментов, необходимых для тестирования, можно использовать образы Docker из наших CI-систем, как описано в нашем репозитории инфраструктуры тестирования.
Mbed TLS можно портировать на множество различных архитектур, ОС и платформ. Прежде чем начать порт, вам могут пригодиться следующие статьи базы знаний:
Mbed TLS в основном написан на портативном C99; однако у него есть несколько требований к платформе, которые выходят за рамки стандарта, но удовлетворяются большинством современных архитектур:
int и size_t должны иметь ширину не менее 32 бит.uint8_t , uint16_t , uint32_t и их подписанные эквиваленты.Архитектура безопасности платформы Arm (PSA) представляет собой целостный набор моделей угроз, анализа безопасности, спецификаций архитектуры аппаратного и встроенного ПО, а также эталонную реализацию встроенного ПО с открытым исходным кодом. PSA предлагает рецепт, основанный на лучших отраслевых практиках, который позволяет последовательно разрабатывать безопасность как на аппаратном уровне, так и на уровне встроенного ПО.
API криптографии PSA предоставляет доступ к набору криптографических примитивов. Он имеет двойную цель. Во-первых, его можно использовать на PSA-совместимой платформе для создания таких сервисов, как безопасная загрузка, безопасное хранение и безопасная связь. Во-вторых, его также можно использовать независимо от других компонентов PSA на любой платформе.
Цели разработки API криптографии PSA включают в себя:
Компания Arm приветствует отзывы о дизайне API. Если вы считаете, что что-то можно улучшить, откройте проблему в нашем репозитории Github. Кроме того, если вы предпочитаете оставить свой отзыв конфиденциально, напишите нам по адресу [email protected] . Все отзывы, полученные по электронной почте, считаются конфиденциальными.
Mbed TLS включает эталонную реализацию API криптографии PSA. Однако он не преследует цели реализовать всю спецификацию; в частности, он не реализует все алгоритмы.
Код X.509 и TLS может использовать криптографию PSA для большинства операций. Чтобы включить эту поддержку, активируйте опцию компиляции MBEDTLS_USE_PSA_CRYPTO в mbedtls_config.h . Обратите внимание, что 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 или более поздней версии. Полный текст этих лицензий см. в файле LICENSE, а дополнительную информацию — в разделе «Лицензия и авторские права» в руководстве по участию.
Этот проект содержит код из других проектов. Этот код находится в каталоге tf-psa-crypto/drivers/ . Исходный текст лицензии включен в подкаталоги проекта, где он отличается от обычной лицензии Mbed TLS, и/или в исходных файлах. Проекты перечислены ниже:
drivers/everest/ : файлы взяты из Project Everest и распространяются по лицензии Apache 2.0.drivers/p256-m/p256-m/ : файлы взяты из репозитория p256-m. Код в исходном репозитории распространяется по лицензии Apache 2.0. Он распространяется в Mbed TLS под двойной лицензией Apache-2.0 ИЛИ GPL-2.0 или более поздней версии с разрешения автора. Мы с благодарностью принимаем сообщения об ошибках и вклады сообщества. Подробную информацию о том, как это сделать, см. в руководстве по участию.
SECURITY.md .SUPPORT.md , чтобы найти другие каналы для обсуждения и поддержки Mbed TLS.
