mbedtls
Mbed TLS 3.6.2
Mbed TLS é uma biblioteca C que implementa primitivas criptográficas, manipulação de certificados X.509 e os protocolos SSL/TLS e DTLS. Sua pequena pegada de código o torna adequado para sistemas embarcados.
Mbed TLS inclui uma implementação de referência da API de criptografia PSA. No momento, esta é uma prévia apenas para fins de avaliação.
O Mbed TLS deve ser criado imediatamente na maioria dos sistemas. Algumas opções específicas da plataforma estão disponíveis no arquivo de configuração totalmente documentado include/mbedtls/mbedtls_config.h , que também é o local onde os recursos podem ser selecionados. Este arquivo pode ser editado manualmente ou de forma mais programática usando o script Python 3 scripts/config.py (use --help para instruções de uso).
As opções do compilador podem ser definidas usando variáveis de ambiente convencionais, como CC e CFLAGS ao usar o sistema de compilação Make e CMake (veja abaixo).
Fornecemos algumas configurações não padrão focadas em casos de uso específicos no diretório configs/ . Você pode ler mais sobre eles em configs/README.txt
A documentação principal do Mbed TLS está disponível em ReadTheDocs.
A documentação da API de criptografia PSA está disponível no GitHub.
Para gerar uma cópia local da documentação da biblioteca em formato HTML, adaptada à sua configuração de tempo de compilação:
make apidoc .apidoc/index.html ou apidoc/modules.html .Para outras fontes de documentação, consulte o documento SUPPORT.
Existem atualmente três sistemas de compilação ativos usados nas versões Mbed TLS:
Os principais sistemas utilizados para desenvolvimento são CMake e GNU Make. Esses sistemas estão sempre completos e atualizados. Os demais devem refletir todas as alterações presentes no sistema de compilação CMake e Make, embora os recursos possam não ser portados para lá automaticamente.
Os sistemas de compilação Make e CMake criam três bibliotecas: libmbedcrypto/libtfpsacrypto, libmbedx509 e libmbedtls. Observe que libmbedtls depende de libmbedx509 e libmbedcrypto/libtfpsacrypto, e libmbedx509 depende de libmbedcrypto/libtfpsacrypto. Como resultado, alguns vinculadores esperam que os sinalizadores estejam em uma ordem específica, por exemplo, o vinculador GNU deseja -lmbedtls -lmbedx509 -lmbedcrypto .
Você precisa das seguintes ferramentas para construir a biblioteca com os makefiles fornecidos:
O ramo development e o ramo de suporte de longo prazo mbedtls-3.6 do Mbed TLS usam um submódulo Git (estrutura). Isso não é necessário apenas para compilar a biblioteca em uma tag de lançamento. Isso não é necessário para consumir um arquivo de lançamento (zip ou tar).
O código fonte do Mbed TLS inclui alguns arquivos que são gerados automaticamente por scripts e cujo conteúdo depende apenas da fonte do Mbed TLS, não da plataforma ou da configuração da biblioteca. Esses arquivos não estão incluídos no ramo de desenvolvimento do Mbed TLS, mas os arquivos gerados estão incluídos nas versões oficiais. Esta seção explica como gerar os arquivos ausentes na ramificação de desenvolvimento.
As seguintes ferramentas são necessárias:
python3 -m pip install --user -r scripts/basic.requirements.txt
python em vez de python3 . Para instalar os pacotes em todo o sistema, omita a opção --user . Se você estiver compilando cruzadamente, deverá definir a variável de ambiente CC como um compilador C para a plataforma host ao gerar os arquivos independentes de configuração.
Qualquer um dos seguintes métodos está disponível para gerar os arquivos independentes de configuração:
make com qualquer destino, ou apenas make , gerará automaticamente os arquivos necessários.make generated_files para gerar todos os arquivos independentes de configuração.tests/scripts/check-generated-files.sh -u para gerar todos os arquivos independentes de configuração.scriptsmake_generated_files.bat para gerar todos os arquivos independentes de configuração.Exigimos GNU Make. Para construir a biblioteca e os programas de exemplo, o GNU Make e um compilador C são suficientes. Alguns dos alvos de construção mais avançados requerem algumas ferramentas Unix/Linux.
Nós intencionalmente usamos apenas um mínimo de funcionalidade nos makefiles para mantê-los tão simples e independentes de diferentes cadeias de ferramentas quanto possível, para permitir que os usuários se movam mais facilmente entre diferentes plataformas. Recomenda-se que os usuários que precisam de mais recursos usem o CMake.
Para construir a partir do código fonte usando GNU Make, basta digitar na linha de comando:
make
Para executar os testes, digite:
make check
Os testes precisam que o Python seja construído e o Perl seja executado. Se você não tiver um deles instalado, você pode pular a construção dos testes com:
make no_test
Você ainda poderá executar um conjunto muito menor de testes com:
programs/test/selftest
Para construir para uma plataforma Windows, você deve usar WINDOWS_BUILD=1 se o destino for Windows, mas o ambiente de construção for semelhante ao Unix (por exemplo, ao fazer compilação cruzada ou compilar a partir de um shell MSYS) e WINDOWS=1 se o O ambiente de compilação é um shell do Windows (por exemplo, usando mingw32-make) (nesse caso, alguns alvos não estarão disponíveis).
Definir a variável SHARED em seu ambiente criará bibliotecas compartilhadas além das bibliotecas estáticas. Definir DEBUG fornece uma compilação de depuração. Você pode substituir CFLAGS e LDFLAGS configurando-os em seu ambiente ou na linha de comando make; as opções de aviso do compilador podem ser substituídas separadamente usando WARNING_CFLAGS . Algumas opções específicas de diretório (por exemplo, diretivas -I ) ainda são preservadas.
Observe que a configuração CFLAGS substitui seu valor padrão de -O2 e a configuração WARNING_CFLAGS substitui seu valor padrão (começando com -Wall -Wextra ), então se você quiser apenas adicionar algumas opções de aviso às opções padrão, você pode fazer isso definindo CFLAGS=-O2 -Werror por exemplo. Definir WARNING_CFLAGS é útil quando você deseja se livrar de seu conteúdo padrão (por exemplo, porque seu compilador não aceita -Wall como opção). As opções específicas do diretório não podem ser substituídas na linha de comando.
Dependendo da sua plataforma, você pode encontrar alguns problemas. Por favor, verifique os Makefiles em library/ , programs/ e tests/ para opções para adicionar ou remover manualmente para plataformas específicas. Você também pode verificar a Base de Conhecimento Mbed TLS para artigos sobre sua plataforma ou problema.
Caso você descubra que precisa fazer outra coisa também, informe-nos, para que possamos adicioná-lo à Base de Conhecimento Mbed TLS.
Para construir o código-fonte usando CMake em um diretório separado (recomendado), basta digitar na linha de comando:
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
Para executar os testes, digite:
ctest
Os conjuntos de testes precisam que o Python seja construído e o Perl seja executado. Se você não tiver um desses instalados, desative os conjuntos de testes com:
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Se você desativou os conjuntos de testes, mas manteve os programas ativados, ainda poderá executar um conjunto muito menor de testes com:
programs/test/selftest
Para configurar o CMake para construir bibliotecas compartilhadas, use:
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Existem muitos modos de construção diferentes disponíveis no sistema de compilação CMake. A maioria deles está disponível para gcc e clang, embora alguns sejam específicos do compilador:
Release . Isso gera o código padrão sem nenhuma informação desnecessária nos arquivos binários.Debug . Isso gera informações de depuração e desativa a otimização do código.Coverage . Isso gera informações de cobertura de código além de informações de depuração.ASan . Isso instrumenta o código com AddressSanitizer para verificar erros de memória. (Isso inclui LeakSanitizer, com versão recente de gcc e clang.) (Com versão recente de clang, este modo também instrumenta o código com UndefinedSanitizer para verificar comportamento indefinido.)ASanDbg . Igual ao ASan, mas mais lento, com informações de depuração e melhores rastreamentos de pilha.MemSan . Isso instrumenta o código com MemorySanitizer para verificar leituras de memória não inicializadas. Experimental, precisa de clang recente no Linux/x86_64.MemSanDbg . Igual ao MemSan, mas mais lento, com informações de depuração, melhores rastreamentos de pilha e rastreamento de origem.Check . Isso ativa os avisos do compilador que dependem da otimização e trata todos os avisos como erros.Alternar os modos de construção no CMake é simples. Para o modo de depuração, digite na linha de comando:
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Para listar outras opções disponíveis do CMake, use:
cmake -LH
Observe que, com o CMake, você não pode ajustar o compilador ou seus sinalizadores após a invocação inicial do cmake. Isso significa que CC=your_cc make e make CC=your_cc não funcionarão (da mesma forma com CFLAGS e outras variáveis). Essas variáveis precisam ser ajustadas ao invocar o cmake pela primeira vez, por exemplo:
CC=your_cc cmake /path/to/mbedtls_source
Se você já invocou o cmake e deseja alterar essas configurações, será necessário remover o diretório de construção e criá-lo novamente.
Observe que é possível construir no local; no entanto, isso substituirá os Makefiles fornecidos (consulte scripts/tmp_ignore_makefiles.sh se quiser evitar que git status os mostre como modificados). Para fazer isso, no diretório de origem Mbed TLS, use:
cmake .
make
Se quiser alterar CC ou CFLAGS posteriormente, você precisará remover o cache do CMake. Isso pode ser feito com o seguinte comando usando GNU find:
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Agora você pode fazer a alteração desejada:
CC=your_cc cmake .
make
Em relação às variáveis, observe também que se você definir CFLAGS ao invocar o cmake, seu valor de CFLAGS não substituirá o conteúdo fornecido pelo cmake (dependendo do modo de construção como visto acima), ele será apenas anexado a ele.
Mbed TLS fornece um arquivo de configuração de pacote para consumo como dependência em outros projetos CMake. Você mesmo pode incluir os alvos CMake do Mbed TLS com:
find_package(MbedTLS)
Se solicitado, defina MbedTLS_DIR como ${YOUR_MBEDTLS_INSTALL_DIR}/cmake . Isso cria os seguintes alvos:
MbedTLS::tfpsacrypto (biblioteca de criptografia)MbedTLS::mbedtls (biblioteca TLS)MbedTLS::mbedx509 (biblioteca X509) Você pode então usá-los diretamente através de target_link_libraries() :
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
Isso vinculará as bibliotecas Mbed TLS à sua biblioteca ou aplicativo e adicionará seus diretórios de inclusão ao seu destino (transitivamente, no caso de bibliotecas de link PUBLIC ou INTERFACE ).
Mbed TLS suporta a construção como um subprojeto CMake. Pode-se usar add_subdirectory() de um projeto CMake pai para incluir Mbed TLS como um subprojeto.
Os arquivos de build do Microsoft Visual Studio são gerados para o Visual Studio 2017.
O arquivo de solução mbedTLS.sln contém todos os projetos básicos necessários para construir a biblioteca e todos os programas. Os arquivos em testes não são gerados e compilados, pois também precisam de ambientes Python e Perl. Contudo, o programa de autoteste em programs/test/ ainda está disponível.
Na ramificação de desenvolvimento do Mbed TLS, os arquivos da solução do Visual Studio precisam ser gerados primeiro, conforme descrito em “Arquivos de origem gerados na ramificação de desenvolvimento”.
Incluímos programas de exemplo para vários recursos e usos diferentes em programs/ . Observe que o objetivo desses programas de exemplo é demonstrar recursos específicos da biblioteca, e o código pode precisar ser adaptado para construir um aplicativo do mundo real.
Mbed TLS inclui um conjunto de testes elaborado em tests/ que inicialmente requer Python para gerar os arquivos de testes (por exemplo, test_suite_ssl.c ). Esses arquivos são gerados a partir de um function file (por exemplo, suites/test_suite_ssl.function ) e um data file (por exemplo, suites/test_suite_ssl.data ). O function file contém as funções de teste. O data file contém os casos de teste, especificados como parâmetros que serão passados para a função de teste.
Para máquinas com shell Unix e OpenSSL (e opcionalmente GnuTLS) instalados, scripts de teste adicionais estão disponíveis:
tests/ssl-opt.sh executa testes de integração para várias opções de TLS (renegociação, retomada, etc.) e testa a interoperabilidade dessas opções com outras implementações.tests/compat.sh testa a interoperabilidade de cada ciphersuite com outras implementações.tests/scripts/test-ref-configs.pl compilações de teste em várias configurações reduzidas.tests/scripts/depends.py teste é construído em configurações com uma única curva, troca de chaves, hash, cifra ou pkalg ativado.tests/scripts/all.sh executa uma combinação dos testes acima, além de mais alguns, com várias opções de construção (como ASan, mbedtls_config.h completo, etc).Em vez de instalar manualmente as versões necessárias de todas as ferramentas necessárias para testes, é possível usar as imagens Docker de nossos sistemas de CI, conforme explicado em nosso repositório de infraestrutura de testes.
Mbed TLS pode ser portado para muitas arquiteturas, sistemas operacionais e plataformas diferentes. Antes de iniciar uma portabilidade, você pode achar úteis os seguintes artigos da Base de Conhecimento:
Mbed TLS é escrito principalmente em C99 portátil; no entanto, possui alguns requisitos de plataforma que vão além do padrão, mas que são atendidos pela maioria das arquiteturas modernas:
int e size_t devem ter pelo menos 32 bits de largura.uint8_t , uint16_t , uint32_t e seus equivalentes assinados devem estar disponíveis.A Platform Security Architecture (PSA) da Arm é um conjunto holístico de modelos de ameaças, análises de segurança, especificações de arquitetura de hardware e firmware e uma implementação de referência de firmware de código aberto. A PSA fornece uma receita, baseada nas melhores práticas do setor, que permite que a segurança seja projetada de forma consistente, tanto em nível de hardware quanto de firmware.
A API de criptografia PSA fornece acesso a um conjunto de primitivas criptográficas. Tem um duplo propósito. Primeiro, ele pode ser usado em uma plataforma compatível com PSA para criar serviços, como inicialização segura, armazenamento seguro e comunicação segura. Em segundo lugar, também pode ser usado independentemente de outros componentes do PSA em qualquer plataforma.
Os objetivos de design da API de criptografia PSA incluem:
Arm agradece comentários sobre o design da API. Se você acha que algo poderia ser melhorado, abra um problema em nosso repositório Github. Alternativamente, se você preferir fornecer seus comentários em particular, envie um email para [email protected] . Todos os comentários recebidos por e-mail são tratados de forma confidencial.
Mbed TLS inclui uma implementação de referência da API de criptografia PSA. Contudo, não pretende implementar toda a especificação; em particular, não implementa todos os algoritmos.
O código X.509 e TLS pode usar criptografia PSA para a maioria das operações. Para ativar esse suporte, ative a opção de compilação MBEDTLS_USE_PSA_CRYPTO em mbedtls_config.h . Observe que o TLS 1.3 usa criptografia PSA para a maioria das operações, independentemente desta opção. Consulte docs/use-psa-crypto.md para obter detalhes.
Mbed TLS oferece suporte a drivers para aceleradores criptográficos, elementos seguros e geradores aleatórios. Este é um trabalho em andamento. Observe que as interfaces do driver ainda não estão totalmente estáveis e podem mudar sem aviso prévio. Pretendemos preservar a compatibilidade com versões anteriores do código do aplicativo (usando a API PSA Crypto), mas o código dos drivers pode precisar ser alterado em futuras versões secundárias do Mbed TLS.
Consulte o exemplo e guia do driver PSA para obter informações sobre como escrever um driver.
Ao usar drivers, geralmente você desejará habilitar duas opções de compilação (consulte o manual de referência para obter mais informações):
MBEDTLS_USE_PSA_CRYPTO é necessário para que o código X.509 e TLS chame os drivers PSA em vez da implementação de software integrada.MBEDTLS_PSA_CRYPTO_CONFIG permite habilitar mecanismos criptográficos PSA sem incluir o código da implementação de software correspondente. Isso ainda não é compatível com todos os mecanismos. A menos que especificamente indicado de outra forma em um arquivo, os arquivos Mbed TLS são fornecidos sob uma licença dupla Apache-2.0 OU GPL-2.0 ou posterior. Consulte o arquivo LICENSE para obter o texto completo dessas licenças e a seção 'Licença e Direitos Autorais' nas diretrizes de contribuição para obter mais informações.
Este projeto contém código de outros projetos. Este código está localizado no diretório tf-psa-crypto/drivers/ . O texto da licença original está incluído nos subdiretórios do projeto, onde difere da licença Mbed TLS normal e/ou nos arquivos de origem. Os projetos estão listados abaixo:
drivers/everest/ : Os arquivos são provenientes do Projeto Everest e são distribuídos sob a licença Apache 2.0.drivers/p256-m/p256-m/ : Os arquivos foram retirados do repositório p256-m. O código no repositório original é distribuído sob a licença Apache 2.0. Ele é distribuído em Mbed TLS sob uma licença dupla Apache-2.0 OU GPL-2.0 ou posterior com permissão do autor. Aceitamos com gratidão relatórios de bugs e contribuições da comunidade. Consulte as diretrizes de contribuição para obter detalhes sobre como fazer isso.
SECURITY.md .SUPPORT.md para outros canais de discussão e suporte sobre Mbed TLS.
