mbedtls
Mbed TLS 3.6.2
Mbed TLS adalah perpustakaan C yang mengimplementasikan primitif kriptografi, manipulasi sertifikat X.509 dan protokol SSL/TLS dan DTLS. Jejak kodenya yang kecil membuatnya cocok untuk sistem tertanam.
Mbed TLS menyertakan implementasi referensi API Kriptografi PSA. Saat ini hanya pratinjau untuk tujuan evaluasi.
Mbed TLS harus dibangun secara out of the box pada sebagian besar sistem. Beberapa opsi khusus platform tersedia dalam file konfigurasi yang terdokumentasi lengkap include/mbedtls/mbedtls_config.h , yang juga merupakan tempat di mana fitur dapat dipilih. File ini dapat diedit secara manual, atau dengan cara yang lebih terprogram menggunakan skrip Python 3 scripts/config.py (gunakan --help untuk petunjuk penggunaan).
Opsi kompiler dapat diatur menggunakan variabel lingkungan konvensional seperti CC dan CFLAGS saat menggunakan sistem build Make dan CMake (lihat di bawah).
Kami menyediakan beberapa konfigurasi non-standar yang berfokus pada kasus penggunaan tertentu di direktori configs/ . Anda dapat membaca lebih lanjut tentang hal tersebut di configs/README.txt
Dokumentasi TLS Mbed utama tersedia melalui ReadTheDocs.
Dokumentasi untuk API Kriptografi PSA tersedia di GitHub.
Untuk menghasilkan salinan lokal dokumentasi perpustakaan dalam format HTML, disesuaikan dengan konfigurasi waktu kompilasi Anda:
make apidoc .apidoc/index.html atau apidoc/modules.html .Untuk sumber dokumentasi lainnya, lihat dokumen DUKUNGAN.
Saat ini ada tiga sistem build aktif yang digunakan dalam rilis Mbed TLS:
Sistem utama yang digunakan untuk pengembangan adalah CMake dan GNU Make. Sistem tersebut selalu lengkap dan terkini. Yang lain harus mencerminkan semua perubahan yang ada dalam sistem CMake dan Make build, meskipun fitur mungkin tidak di-porting ke sana secara otomatis.
Sistem pembangunan Make dan CMake membuat tiga perpustakaan: libmbedcrypto/libtfpsacrypto, libmbedx509, dan libmbedtls. Perhatikan bahwa libmbedtls bergantung pada libmbedx509 dan libmbedcrypto/libtfpsacrypto, dan libmbedx509 bergantung pada libmbedcrypto/libtfpsacrypto. Akibatnya, beberapa linker akan mengharapkan flag berada dalam urutan tertentu, misalnya linker GNU menginginkan -lmbedtls -lmbedx509 -lmbedcrypto .
Anda memerlukan alat berikut untuk membangun perpustakaan dengan makefile yang disediakan:
Cabang development dan cabang dukungan jangka panjang mbedtls-3.6 dari Mbed TLS menggunakan submodul Git (kerangka kerja). Ini tidak diperlukan hanya untuk mengkompilasi perpustakaan pada tag rilis. Ini tidak diperlukan untuk menggunakan arsip rilis (zip atau tar).
Kode sumber Mbed TLS menyertakan beberapa file yang dibuat secara otomatis oleh skrip dan kontennya hanya bergantung pada sumber Mbed TLS, bukan pada platform atau konfigurasi perpustakaan. File-file ini tidak termasuk dalam cabang pengembangan Mbed TLS, tetapi file yang dihasilkan disertakan dalam rilis resmi. Bagian ini menjelaskan cara menghasilkan file yang hilang di cabang pengembangan.
Alat-alat berikut diperlukan:
python3 -m pip install --user -r scripts/basic.requirements.txt
python alih-alih python3 . Untuk menginstal paket di seluruh sistem, hilangkan opsi --user . Jika Anda melakukan kompilasi silang, Anda harus mengatur variabel lingkungan CC ke kompiler C untuk platform host saat membuat file yang tidak bergantung pada konfigurasi.
Salah satu metode berikut tersedia untuk menghasilkan file yang tidak bergantung pada konfigurasi:
make dengan target apa pun, atau hanya make , akan secara otomatis menghasilkan file yang diperlukan.make generated_files untuk menghasilkan semua file yang tidak bergantung pada konfigurasi.tests/scripts/check-generated-files.sh -u untuk menghasilkan semua file yang tidak bergantung pada konfigurasi.scriptsmake_generated_files.bat untuk menghasilkan semua file yang tidak bergantung pada konfigurasi.Kami membutuhkan GNU Make. Untuk membangun perpustakaan dan program contoh, GNU Make dan kompiler C sudah cukup. Beberapa target pembangunan yang lebih maju memerlukan beberapa alat Unix/Linux.
Kami sengaja hanya menggunakan fungsionalitas minimal dalam makefile agar tetap sesederhana dan independen terhadap rangkaian alat yang berbeda, agar pengguna lebih mudah berpindah antar platform yang berbeda. Pengguna yang membutuhkan fitur lebih disarankan untuk menggunakan CMake.
Untuk membangun dari kode sumber menggunakan GNU Make, cukup masukkan pada baris perintah:
make
Untuk menjalankan tes, masukkan:
make check
Pengujian memerlukan Python untuk dibuat dan Perl untuk dijalankan. Jika Anda belum menginstal salah satunya, Anda dapat melewati pembuatan pengujian dengan:
make no_test
Anda masih dapat menjalankan serangkaian pengujian yang jauh lebih kecil dengan:
programs/test/selftest
Untuk membangun platform Windows, Anda harus menggunakan WINDOWS_BUILD=1 jika targetnya adalah Windows tetapi lingkungan pembangunannya mirip Unix (misalnya saat kompilasi silang, atau kompilasi dari shell MSYS), dan WINDOWS=1 jika lingkungan build adalah shell Windows (misalnya menggunakan mingw32-make) (dalam hal ini beberapa target tidak akan tersedia).
Menyetel variabel SHARED di lingkungan Anda akan membangun perpustakaan bersama selain perpustakaan statis. Menyetel DEBUG memberi Anda build debug. Anda dapat mengganti CFLAGS dan LDFLAGS dengan mengaturnya di lingkungan Anda atau di baris perintah make; opsi peringatan kompiler dapat diganti secara terpisah menggunakan WARNING_CFLAGS . Beberapa opsi khusus direktori (misalnya, arahan -I ) masih dipertahankan.
Harap dicatat bahwa pengaturan CFLAGS mengesampingkan nilai default -O2 dan pengaturan WARNING_CFLAGS mengesampingkan nilai defaultnya (dimulai dengan -Wall -Wextra ), jadi jika Anda hanya ingin menambahkan beberapa opsi peringatan ke default, Anda dapat melakukannya dengan mengatur CFLAGS=-O2 -Werror misalnya. Pengaturan WARNING_CFLAGS berguna ketika Anda ingin membuang konten defaultnya (misalnya karena kompiler Anda tidak menerima -Wall sebagai opsi). Opsi khusus direktori tidak dapat diganti dari baris perintah.
Tergantung pada platform Anda, Anda mungkin mengalami beberapa masalah. Silakan periksa Makefiles di library/ , programs/ dan tests/ untuk opsi untuk menambah atau menghapus secara manual untuk platform tertentu. Anda juga dapat memeriksa Basis Pengetahuan Mbed TLS untuk artikel tentang platform atau masalah Anda.
Jika Anda merasa perlu melakukan hal lain juga, harap beri tahu kami, sehingga kami dapat menambahkannya ke Basis Pengetahuan Mbed TLS.
Untuk membangun sumber menggunakan CMake di direktori terpisah (disarankan), cukup masukkan di baris perintah:
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
Untuk menjalankan tes, masukkan:
ctest
Rangkaian pengujian memerlukan Python untuk dibuat dan Perl untuk dieksekusi. Jika Anda belum menginstal salah satu dari ini, Anda dapat menonaktifkan rangkaian pengujian dengan:
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
Jika Anda menonaktifkan rangkaian pengujian, namun tetap mengaktifkan program, Anda masih dapat menjalankan serangkaian pengujian yang jauh lebih kecil dengan:
programs/test/selftest
Untuk mengonfigurasi CMake untuk membangun perpustakaan bersama, gunakan:
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
Ada banyak mode build berbeda yang tersedia dalam sistem build CMake. Sebagian besar tersedia untuk gcc dan clang, meskipun beberapa di antaranya khusus untuk compiler:
Release . Ini menghasilkan kode default tanpa informasi yang tidak diperlukan dalam file biner.Debug . Ini menghasilkan informasi debug dan menonaktifkan optimasi kode.Coverage . Ini menghasilkan informasi cakupan kode selain informasi debug.ASan . Ini melengkapi kode dengan AddressSanitizer untuk memeriksa kesalahan memori. (Ini termasuk LeakSanitizer, dengan gcc dan clang versi terbaru.) (Dengan clang versi terbaru, mode ini juga melengkapi kode dengan UndefinisiSanitizer untuk memeriksa perilaku tidak terdefinisi.)ASanDbg . Sama seperti ASan tetapi lebih lambat, dengan informasi debug dan pelacakan tumpukan yang lebih baik.MemSan . Ini melengkapi kode dengan MemorySanitizer untuk memeriksa pembacaan memori yang tidak diinisialisasi. Eksperimental, memerlukan dentang terbaru di Linux/x86_64.MemSanDbg . Sama seperti MemSan tetapi lebih lambat, dengan informasi debug, pelacakan tumpukan dan pelacakan asal yang lebih baik.Check . Ini mengaktifkan peringatan kompiler yang bergantung pada optimasi dan menganggap semua peringatan sebagai kesalahan.Beralih mode build di CMake itu sederhana. Untuk mode debug, masukkan di baris perintah:
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
Untuk mencantumkan opsi CMake lain yang tersedia, gunakan:
cmake -LH
Perhatikan bahwa, dengan CMake, Anda tidak dapat menyesuaikan kompiler atau flagnya setelah pemanggilan awal cmake. Artinya CC=your_cc make dan make CC=your_cc tidak akan berfungsi (sama halnya dengan CFLAGS dan variabel lainnya). Variabel-variabel ini perlu disesuaikan saat pertama kali memanggil cmake, misalnya:
CC=your_cc cmake /path/to/mbedtls_source
Jika Anda sudah memanggil cmake dan ingin mengubah pengaturan tersebut, Anda perlu menghapus direktori build dan membuatnya kembali.
Perhatikan bahwa pembangunan di tempat dapat dilakukan; namun ini akan menimpa Makefile yang disediakan (lihat scripts/tmp_ignore_makefiles.sh jika Anda ingin mencegah git status menampilkannya sebagai diubah). Untuk melakukannya, dari direktori sumber Mbed TLS, gunakan:
cmake .
make
Jika Anda ingin mengubah CC atau CFLAGS setelahnya, Anda perlu menghapus cache CMake. Ini dapat dilakukan dengan perintah berikut menggunakan GNU find:
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
Anda sekarang dapat melakukan perubahan yang diinginkan:
CC=your_cc cmake .
make
Mengenai variabel, perhatikan juga bahwa jika Anda menyetel CFLAGS saat menjalankan cmake, nilai CFLAGS Anda tidak menggantikan konten yang disediakan oleh cmake (tergantung pada mode build seperti yang terlihat di atas), nilai tersebut hanya ditambahkan di depannya.
Mbed TLS menyediakan file konfigurasi paket untuk dikonsumsi sebagai ketergantungan dalam proyek CMake lainnya. Anda dapat memasukkan sendiri target CMake Mbed TLS dengan:
find_package(MbedTLS)
Jika diminta, setel MbedTLS_DIR ke ${YOUR_MBEDTLS_INSTALL_DIR}/cmake . Hal ini menciptakan target berikut:
MbedTLS::tfpsacrypto (Perpustakaan kripto)MbedTLS::mbedtls (perpustakaan TLS)MbedTLS::mbedx509 (perpustakaan X509) Anda kemudian dapat menggunakannya secara langsung melalui target_link_libraries() :
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
Ini akan menautkan perpustakaan TLS Mbed ke perpustakaan atau aplikasi Anda, dan menambahkan direktori penyertaannya ke target Anda (secara transitif, dalam kasus perpustakaan tautan PUBLIC atau INTERFACE ).
Mbed TLS mendukung pembangunan sebagai subproyek CMake. Seseorang dapat menggunakan add_subdirectory() dari proyek induk CMake untuk menyertakan Mbed TLS sebagai subproyek.
File build untuk Microsoft Visual Studio dibuat untuk Visual Studio 2017.
File solusi mbedTLS.sln berisi semua proyek dasar yang diperlukan untuk membangun perpustakaan dan semua program. File dalam pengujian tidak dibuat dan dikompilasi, karena ini memerlukan lingkungan Python dan Perl juga. Namun, program selftest di programs/test/ masih tersedia.
Di cabang pengembangan Mbed TLS, file solusi Visual Studio perlu dibuat terlebih dahulu seperti yang dijelaskan dalam “File sumber yang dihasilkan di cabang pengembangan”.
Kami telah menyertakan contoh program untuk banyak fitur dan kegunaan berbeda dalam programs/ . Harap dicatat bahwa tujuan dari contoh program ini adalah untuk mendemonstrasikan fitur spesifik perpustakaan, dan kodenya mungkin perlu diadaptasi untuk membangun aplikasi dunia nyata.
Mbed TLS menyertakan rangkaian pengujian yang rumit dalam tests/ yang awalnya memerlukan Python untuk menghasilkan file pengujian (misalnya test_suite_ssl.c ). File-file ini dihasilkan dari function file (misalnya suites/test_suite_ssl.function ) dan data file (misalnya suites/test_suite_ssl.data ). function file berisi fungsi pengujian. data file berisi kasus uji, yang ditentukan sebagai parameter yang akan diteruskan ke fungsi pengujian.
Untuk mesin dengan shell Unix dan OpenSSL (dan opsional GnuTLS), tersedia skrip pengujian tambahan:
tests/ssl-opt.sh menjalankan tes integrasi untuk berbagai opsi TLS (negosiasi ulang, dimulainya kembali, dll.) dan menguji interoperabilitas opsi ini dengan implementasi lain.tests/compat.sh menguji interoperabilitas setiap ciphersuite dengan implementasi lainnya.tests/scripts/test-ref-configs.pl tes dibuat dalam berbagai konfigurasi yang dikurangi.tests/scripts/depends.py tes dibangun dalam konfigurasi dengan kurva tunggal, pertukaran kunci, hash, sandi, atau pkalg aktif.tests/scripts/all.sh menjalankan kombinasi tes di atas, ditambah beberapa tes lainnya, dengan berbagai opsi build (seperti ASan, mbedtls_config.h penuh, dll).Daripada menginstal secara manual versi yang diperlukan dari semua alat yang diperlukan untuk pengujian, Anda dapat menggunakan image Docker dari sistem CI kami, seperti yang dijelaskan dalam repositori infrastruktur pengujian kami.
Mbed TLS dapat di-porting ke berbagai arsitektur, OS, dan platform. Sebelum memulai port, Anda mungkin menemukan artikel Basis Pengetahuan berikut berguna:
Mbed TLS sebagian besar ditulis dalam C99 portabel; namun, ia memiliki beberapa persyaratan platform yang melampaui standar, namun dipenuhi oleh sebagian besar arsitektur modern:
int dan size_t harus memiliki lebar minimal 32 bit.uint8_t , uint16_t , uint32_t dan padanannya yang bertanda tangan harus tersedia.Arsitektur Keamanan Platform (PSA) Arm adalah serangkaian model ancaman, analisis keamanan, spesifikasi arsitektur perangkat keras dan firmware yang holistik, dan implementasi referensi firmware sumber terbuka. PSA memberikan resep, berdasarkan praktik terbaik industri, yang memungkinkan keamanan dirancang secara konsisten, baik pada tingkat perangkat keras maupun firmware.
API kriptografi PSA menyediakan akses ke sekumpulan primitif kriptografi. Ini memiliki tujuan ganda. Pertama, dapat digunakan dalam platform yang sesuai dengan PSA untuk membangun layanan, seperti boot aman, penyimpanan aman, dan komunikasi aman. Kedua, ini juga dapat digunakan secara independen dari komponen PSA lainnya pada platform apa pun.
Tujuan desain API kriptografi PSA meliputi:
Arm menyambut baik masukan mengenai desain API. Jika menurut Anda ada sesuatu yang bisa diperbaiki, silakan buka masalah di repositori Github kami. Atau, jika Anda lebih memilih untuk memberikan tanggapan Anda secara pribadi, silakan kirim email kepada kami di [email protected] . Semua umpan balik yang diterima melalui email diperlakukan secara rahasia.
Mbed TLS menyertakan implementasi referensi API Kriptografi PSA. Namun, hal ini tidak bertujuan untuk mengimplementasikan keseluruhan spesifikasi; khususnya ia tidak mengimplementasikan semua algoritma.
Kode X.509 dan TLS dapat menggunakan kriptografi PSA untuk sebagian besar operasi. Untuk mengaktifkan dukungan ini, aktifkan opsi kompilasi MBEDTLS_USE_PSA_CRYPTO di mbedtls_config.h . Perhatikan bahwa TLS 1.3 menggunakan kriptografi PSA untuk sebagian besar operasi apa pun opsi ini. Lihat docs/use-psa-crypto.md untuk detailnya.
Mbed TLS mendukung driver untuk akselerator kriptografi, elemen aman, dan generator acak. Ini sedang dalam proses. Harap diperhatikan bahwa antarmuka driver belum sepenuhnya stabil dan dapat berubah tanpa pemberitahuan. Kami bermaksud mempertahankan kompatibilitas ke belakang untuk kode aplikasi (menggunakan PSA Crypto API), namun kode driver mungkin harus diubah dalam rilis kecil Mbed TLS di masa mendatang.
Silakan lihat contoh driver PSA dan panduannya untuk informasi cara menulis driver.
Saat menggunakan driver, biasanya Anda ingin mengaktifkan dua opsi kompilasi (lihat manual referensi untuk informasi lebih lanjut):
MBEDTLS_USE_PSA_CRYPTO diperlukan agar kode X.509 dan TLS memanggil driver PSA daripada implementasi perangkat lunak bawaan.MBEDTLS_PSA_CRYPTO_CONFIG memungkinkan Anda mengaktifkan mekanisme kriptografi PSA tanpa menyertakan kode implementasi perangkat lunak terkait. Hal ini belum didukung untuk semua mekanisme. Kecuali dinyatakan lain secara khusus dalam file, file Mbed TLS disediakan di bawah lisensi ganda Apache-2.0 ATAU GPL-2.0-atau-yang lebih baru. Lihat file LISENSI untuk teks lengkap lisensi ini, dan bagian 'Lisensi dan Hak Cipta' di pedoman kontribusi untuk informasi lebih lanjut.
Proyek ini berisi kode dari proyek lain. Kode ini terletak di dalam direktori tf-psa-crypto/drivers/ . Teks lisensi asli disertakan dalam subdirektori proyek, yang berbeda dari lisensi TLS Mbed normal, dan/atau dalam file sumber. Proyek-proyek tersebut tercantum di bawah ini:
drivers/everest/ : File berasal dari Project Everest dan didistribusikan di bawah lisensi Apache 2.0.drivers/p256-m/p256-m/ : File telah diambil dari repositori p256-m. Kode dalam repositori asli didistribusikan di bawah lisensi Apache 2.0. Ini didistribusikan dalam Mbed TLS di bawah lisensi ganda Apache-2.0 ATAU GPL-2.0-atau-yang lebih baru dengan izin dari penulis. Kami dengan senang hati menerima laporan bug dan kontribusi dari komunitas. Silakan lihat pedoman kontribusi untuk rincian tentang cara melakukan hal ini.
SECURITY.md .SUPPORT.md untuk saluran lain untuk diskusi dan dukungan tentang Mbed TLS.
