mbedtls
Mbed TLS 3.6.2
Mbed TLS es una biblioteca C que implementa primitivas criptográficas, manipulación de certificados X.509 y los protocolos SSL/TLS y DTLS. Su pequeño tamaño de código lo hace adecuado para sistemas integrados.
Mbed TLS incluye una implementación de referencia de la API de criptografía PSA. Actualmente, esta es una vista previa solo con fines de evaluación.
Mbed TLS debería estar listo para usar en la mayoría de los sistemas. Algunas opciones específicas de la plataforma están disponibles en el archivo de configuración completamente documentado include/mbedtls/mbedtls_config.h , que también es el lugar donde se pueden seleccionar las funciones. Este archivo se puede editar manualmente o de forma más programática usando el script de Python 3 scripts/config.py (use --help para obtener instrucciones de uso).
Las opciones del compilador se pueden configurar usando variables de entorno convencionales como CC y CFLAGS cuando se usa el sistema de compilación Make y CMake (ver más abajo).
Proporcionamos algunas configuraciones no estándar centradas en casos de uso específicos en el directorio configs/ . Puedes leer más sobre ellos en configs/README.txt
La documentación principal de Mbed TLS está disponible a través de ReadTheDocs.
La documentación para la API de criptografía de PSA está disponible en GitHub.
Para generar una copia local de la documentación de la biblioteca en formato HTML, adaptada a su configuración en tiempo de compilación:
make apidoc .apidoc/index.html o apidoc/modules.html .Para otras fuentes de documentación, consulte el documento de SOPORTE.
Actualmente, se utilizan tres sistemas de compilación activos en las versiones de Mbed TLS:
Los principales sistemas utilizados para el desarrollo son CMake y GNU Make. Esos sistemas están siempre completos y actualizados. Los demás deberían reflejar todos los cambios presentes en CMake y el sistema de compilación Make, aunque es posible que las funciones no se transfieran allí automáticamente.
Los sistemas de compilación Make y CMake crean tres bibliotecas: libmbedcrypto/libtfpsacrypto, libmbedx509 y libmbedtls. Tenga en cuenta que libmbedtls depende de libmbedx509 y libmbedcrypto/libtfpsacrypto, y libmbedx509 depende de libmbedcrypto/libtfpsacrypto. Como resultado, algunos enlazadores esperarán que las banderas estén en un orden específico, por ejemplo, el enlazador GNU quiere -lmbedtls -lmbedx509 -lmbedcrypto .
Necesita las siguientes herramientas para crear la biblioteca con los archivos MAKE proporcionados:
La rama development y la rama de soporte a largo plazo mbedtls-3.6 de Mbed TLS utilizan un submódulo Git (marco). Esto no es necesario simplemente para compilar la biblioteca en una etiqueta de lanzamiento. Esto no es necesario para consumir un archivo de lanzamiento (zip o tar).
El código fuente de Mbed TLS incluye algunos archivos que se generan automáticamente mediante scripts y cuyo contenido depende únicamente de la fuente de Mbed TLS, no de la plataforma ni de la configuración de la biblioteca. Estos archivos no están incluidos en la rama de desarrollo de Mbed TLS, pero los archivos generados sí están incluidos en las versiones oficiales. Esta sección explica cómo generar los archivos que faltan en la rama de desarrollo.
Se requieren las siguientes herramientas:
python3 -m pip install --user -r scripts/basic.requirements.txt
python en lugar de python3 . Para instalar los paquetes en todo el sistema, omita la opción --user . Si está realizando una compilación cruzada, debe configurar la variable de entorno CC en un compilador C para la plataforma host al generar los archivos independientes de la configuración.
Cualquiera de los siguientes métodos está disponible para generar archivos independientes de la configuración:
make con cualquier objetivo, o simplemente make , generará automáticamente los archivos necesarios.make generated_files para generar todos los archivos independientes de la configuración.tests/scripts/check-generated-files.sh -u para generar todos los archivos independientes de la configuración.scriptsmake_generated_files.bat para generar todos los archivos independientes de la configuración.Requerimos GNU Make. Para construir la biblioteca y los programas de muestra, son suficientes GNU Make y un compilador de C. Algunos de los objetivos de compilación más avanzados requieren algunas herramientas de Unix/Linux.
Solo utilizamos intencionalmente un mínimo de funcionalidad en los archivos MAKE para mantenerlos lo más simples e independientes posible de diferentes cadenas de herramientas, para permitir a los usuarios moverse más fácilmente entre diferentes plataformas. Se recomienda a los usuarios que necesiten más funciones que utilicen CMake.
Para construir desde el código fuente usando GNU Make, simplemente ingrese en la línea de comando:
make
Para ejecutar las pruebas, ingrese:
make check
Las pruebas necesitan que se cree Python y que se ejecute Perl. Si no tiene ninguno de ellos instalado, puede omitir la creación de pruebas con:
make no_test
Aún podrás ejecutar un conjunto mucho más pequeño de pruebas con:
programs/test/selftest
Para compilar para una plataforma Windows, debe usar WINDOWS_BUILD=1 si el destino es Windows pero el entorno de compilación es similar a Unix (por ejemplo, al compilar de forma cruzada o desde un shell MSYS), y WINDOWS=1 si el El entorno de compilación es un shell de Windows (por ejemplo, usando mingw32-make) (en ese caso, algunos objetivos no estarán disponibles).
Configurar la variable SHARED en su entorno creará bibliotecas compartidas además de las bibliotecas estáticas. Configurar DEBUG le brinda una compilación de depuración. Puede anular CFLAGS y LDFLAGS configurándolos en su entorno o en la línea de comando make; Las opciones de advertencia del compilador se pueden anular por separado usando WARNING_CFLAGS . Algunas opciones específicas del directorio (por ejemplo, directivas -I ) aún se conservan.
Tenga en cuenta que configurar CFLAGS anula su valor predeterminado de -O2 y configurar WARNING_CFLAGS anula su valor predeterminado (comenzando con -Wall -Wextra ), por lo que si solo desea agregar algunas opciones de advertencia a las predeterminadas, puede hacerlo configurando CFLAGS=-O2 -Werror por ejemplo. Configurar WARNING_CFLAGS es útil cuando desea deshacerse de su contenido predeterminado (por ejemplo, porque su compilador no acepta -Wall como opción). Las opciones específicas del directorio no se pueden anular desde la línea de comando.
Dependiendo de su plataforma, es posible que tenga algunos problemas. Consulte los Makefiles en library/ , programs/ y tests/ para ver opciones para agregar o eliminar manualmente para plataformas específicas. También puede consultar la base de conocimientos de Mbed TLS para obtener artículos sobre su plataforma o problema.
En caso de que descubra que también necesita hacer algo más, háganoslo saber para que podamos agregarlo a la base de conocimientos de Mbed TLS.
Para compilar el código fuente usando CMake en un directorio separado (recomendado), simplemente ingrese en la línea de comando:
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
Para ejecutar las pruebas, ingrese:
ctest
Los conjuntos de pruebas necesitan que se cree Python y que se ejecute Perl. Si no tiene uno de estos instalado, querrá deshabilitar los conjuntos de pruebas con:
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Si deshabilitó los conjuntos de pruebas, pero mantuvo los programas habilitados, aún puede ejecutar un conjunto de pruebas mucho más pequeño con:
programs/test/selftest
Para configurar CMake para crear bibliotecas compartidas, utilice:
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Hay muchos modos de compilación diferentes disponibles dentro del sistema de compilación CMake. La mayoría de ellos están disponibles para gcc y clang, aunque algunos son específicos del compilador:
Release . Esto genera el código predeterminado sin ninguna información innecesaria en los archivos binarios.Debug . Esto genera información de depuración y deshabilita la optimización del código.Coverage . Esto genera información de cobertura de código además de información de depuración.ASan . Esto instrumenta el código con AddressSanitizer para verificar si hay errores de memoria. (Esto incluye LeakSanitizer, con la versión reciente de gcc y clang). (Con la versión reciente de clang, este modo también instrumenta el código con UndefinedSanitizer para verificar si hay un comportamiento indefinido).ASanDbg . Igual que ASan pero más lento, con información de depuración y mejores seguimientos de pila.MemSan . Esto instrumenta el código con MemorySanitizer para verificar si hay lecturas de memoria no inicializadas. Experimental, necesita un sonido metálico reciente en Linux/x86_64.MemSanDbg . Igual que MemSan pero más lento, con información de depuración, mejores seguimientos de pila y seguimiento de origen.Check . Esto activa las advertencias del compilador que dependen de la optimización y trata todas las advertencias como errores.Cambiar los modos de compilación en CMake es simple. Para el modo de depuración, ingrese en la línea de comando:
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Para enumerar otras opciones de CMake disponibles, utilice:
cmake -LH
Tenga en cuenta que, con CMake, no puede ajustar el compilador ni sus indicadores después de la invocación inicial de cmake. Esto significa que CC=your_cc make y make CC=your_cc no funcionarán (de manera similar con CFLAGS y otras variables). Estas variables deben ajustarse al invocar cmake por primera vez, por ejemplo:
CC=your_cc cmake /path/to/mbedtls_source
Si ya invocó cmake y desea cambiar esa configuración, debe eliminar el directorio de compilación y crearlo nuevamente.
Tenga en cuenta que es posible construir en el lugar; Sin embargo, esto sobrescribirá los Makefiles proporcionados (consulte scripts/tmp_ignore_makefiles.sh si desea evitar que git status los muestre como modificados). Para hacerlo, desde el directorio fuente de Mbed TLS, use:
cmake .
make
Si luego desea cambiar CC o CFLAGS , deberá eliminar el caché de CMake. Esto se puede hacer con el siguiente comando usando GNU find:
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Ahora puede realizar el cambio deseado:
CC=your_cc cmake .
make
Con respecto a las variables, también tenga en cuenta que si configura CFLAGS al invocar cmake, su valor de CFLAGS no anula el contenido proporcionado por cmake (dependiendo del modo de compilación como se ve arriba), simplemente se antepone a él.
Mbed TLS proporciona un archivo de configuración de paquete para su consumo como dependencia en otros proyectos de CMake. Puede incluir usted mismo los objetivos CMake de Mbed TLS con:
find_package(MbedTLS)
Si se le solicita, configure MbedTLS_DIR en ${YOUR_MBEDTLS_INSTALL_DIR}/cmake . Esto crea los siguientes objetivos:
MbedTLS::tfpsacrypto (biblioteca de criptomonedas)MbedTLS::mbedtls (biblioteca TLS)MbedTLS::mbedx509 (biblioteca X509) Luego puedes usarlos directamente a través de target_link_libraries() :
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
Esto vinculará las bibliotecas Mbed TLS a su biblioteca o aplicación y agregará sus directorios de inclusión a su destino (transitivamente, en el caso de bibliotecas de enlace PUBLIC o INTERFACE ).
Mbed TLS admite la construcción como un subproyecto CMake. Se puede usar add_subdirectory() de un proyecto principal de CMake para incluir Mbed TLS como subproyecto.
Los archivos de compilación para Microsoft Visual Studio se generan para Visual Studio 2017.
El archivo de solución mbedTLS.sln contiene todos los proyectos básicos necesarios para construir la biblioteca y todos los programas. Los archivos de las pruebas no se generan ni compilan, ya que también necesitan entornos Python y Perl. Sin embargo, el programa de autoprueba en programs/test/ todavía está disponible.
En la rama de desarrollo de Mbed TLS, los archivos de la solución de Visual Studio deben generarse primero como se describe en "Archivos fuente generados en la rama de desarrollo".
Hemos incluido programas de ejemplo para muchas características y usos diferentes en programs/ . Tenga en cuenta que el objetivo de estos programas de muestra es demostrar características específicas de la biblioteca y es posible que sea necesario adaptar el código para crear una aplicación del mundo real.
Mbed TLS incluye un conjunto de pruebas elaborado en tests/ que inicialmente requiere Python para generar los archivos de prueba (por ejemplo, test_suite_ssl.c ). Estos archivos se generan a partir de un function file (por ejemplo, suites/test_suite_ssl.function ) y un data file (por ejemplo, suites/test_suite_ssl.data ). El function file contiene las funciones de prueba. El data file contiene los casos de prueba, especificados como parámetros que se pasarán a la función de prueba.
Para máquinas con un shell Unix y OpenSSL (y opcionalmente GnuTLS) instalado, hay disponibles scripts de prueba adicionales:
tests/ssl-opt.sh ejecuta pruebas de integración para varias opciones de TLS (renegociación, reanudación, etc.) y prueba la interoperabilidad de estas opciones con otras implementaciones.tests/compat.sh prueba la interoperabilidad de cada conjunto de cifrado con otras implementaciones.tests/scripts/test-ref-configs.pl compilaciones de prueba en varias configuraciones reducidas.tests/scripts/depends.py se basa en configuraciones con una sola curva, intercambio de claves, hash, cifrado o pkalg activado.tests/scripts/all.sh ejecuta una combinación de las pruebas anteriores, además de algunas más, con varias opciones de compilación (como ASan, mbedtls_config.h completo, etc.).En lugar de instalar manualmente las versiones requeridas de todas las herramientas necesarias para las pruebas, es posible utilizar las imágenes de Docker de nuestros sistemas CI, como se explica en nuestro repositorio de infraestructura de pruebas.
Mbed TLS se puede migrar a muchas arquitecturas, sistemas operativos y plataformas diferentes. Antes de iniciar una migración, puede que le resulten útiles los siguientes artículos de la base de conocimientos:
Mbed TLS está escrito principalmente en C99 portátil; sin embargo, tiene algunos requisitos de plataforma que van más allá del estándar, pero que la mayoría de las arquitecturas modernas cumplen:
int y size_t deben tener al menos 32 bits de ancho.uint8_t , uint16_t , uint32_t y sus equivalentes con signo deben estar disponibles.La arquitectura de seguridad de plataforma (PSA) de Arm es un conjunto holístico de modelos de amenazas, análisis de seguridad, especificaciones de arquitectura de hardware y firmware, y una implementación de referencia de firmware de código abierto. PSA proporciona una receta, basada en las mejores prácticas de la industria, que permite diseñar la seguridad de manera consistente, tanto a nivel de hardware como de firmware.
La API de criptografía PSA proporciona acceso a un conjunto de primitivas criptográficas. Tiene un doble propósito. En primer lugar, se puede utilizar en una plataforma compatible con PSA para crear servicios, como arranque seguro, almacenamiento seguro y comunicación segura. En segundo lugar, también se puede utilizar independientemente de otros componentes de PSA en cualquier plataforma.
Los objetivos de diseño de la API de criptografía PSA incluyen:
Arm agradece los comentarios sobre el diseño de la API. Si cree que algo podría mejorarse, abra un problema en nuestro repositorio de Github. Alternativamente, si prefiere enviar sus comentarios de forma privada, envíenos un correo electrónico a [email protected] . Todos los comentarios recibidos por correo electrónico se tratan de forma confidencial.
Mbed TLS incluye una implementación de referencia de la API de criptografía PSA. Sin embargo, no pretende implementar toda la especificación; en particular, no implementa todos los algoritmos.
El código X.509 y TLS puede utilizar criptografía PSA para la mayoría de las operaciones. Para habilitar este soporte, active la opción de compilación MBEDTLS_USE_PSA_CRYPTO en mbedtls_config.h . Tenga en cuenta que TLS 1.3 utiliza criptografía PSA para la mayoría de las operaciones independientemente de esta opción. Consulte docs/use-psa-crypto.md para obtener más detalles.
Mbed TLS admite controladores para aceleradores criptográficos, elementos seguros y generadores aleatorios. Este es un trabajo en progreso. Tenga en cuenta que las interfaces del controlador aún no son completamente estables y pueden cambiar sin previo aviso. Tenemos la intención de preservar la compatibilidad con versiones anteriores del código de la aplicación (utilizando PSA Crypto API), pero es posible que el código de los controladores deba cambiar en futuras versiones menores de Mbed TLS.
Consulte el ejemplo y la guía del controlador PSA para obtener información sobre cómo escribir un controlador.
Cuando utilice controladores, generalmente querrá habilitar dos opciones de compilación (consulte el manual de referencia para obtener más información):
MBEDTLS_USE_PSA_CRYPTO es necesario para que el código X.509 y TLS llame a los controladores PSA en lugar de a la implementación de software integrada.MBEDTLS_PSA_CRYPTO_CONFIG le permite habilitar mecanismos criptográficos PSA sin incluir el código de la implementación de software correspondiente. Esto aún no es compatible con todos los mecanismos. A menos que se indique específicamente lo contrario en un archivo, los archivos Mbed TLS se proporcionan bajo una licencia dual Apache-2.0 O GPL-2.0 o posterior. Consulte el archivo LICENCIA para obtener el texto completo de estas licencias y la sección 'Licencia y derechos de autor' en las pautas de contribución para obtener más información.
Este proyecto contiene código de otros proyectos. Este código se encuentra dentro del directorio tf-psa-crypto/drivers/ . El texto de la licencia original se incluye dentro de los subdirectorios del proyecto, donde difiere de la licencia Mbed TLS normal, y/o en los archivos fuente. Los proyectos se enumeran a continuación:
drivers/everest/ : Los archivos provienen del Proyecto Everest y se distribuyen bajo la licencia Apache 2.0.drivers/p256-m/p256-m/ : Los archivos se han tomado del repositorio de p256-m. El código del repositorio original se distribuye bajo la licencia Apache 2.0. Se distribuye en Mbed TLS bajo una licencia dual Apache-2.0 O GPL-2.0 o posterior con permiso del autor. Aceptamos con gratitud informes de errores y contribuciones de la comunidad. Consulte las pautas de contribución para obtener detalles sobre cómo hacer esto.
SECURITY.md .SUPPORT.md para conocer otros canales de discusión y soporte sobre Mbed TLS.
