mbedtls
Mbed TLS 3.6.2
Mbed TLS هي مكتبة C تنفذ أساسيات التشفير ومعالجة شهادات X.509 وبروتوكولات SSL/TLS وDTLS. إن بصمة الكود الصغيرة الخاصة بها تجعلها مناسبة للأنظمة المدمجة.
يتضمن Mbed TLS تطبيقًا مرجعيًا لـ PSA Cryptography API. هذه حاليًا معاينة لأغراض التقييم فقط.
يجب أن يتم إنشاء Mbed TLS خارج الصندوق في معظم الأنظمة. تتوفر بعض الخيارات الخاصة بالنظام الأساسي في ملف التكوين الموثق بالكامل include/mbedtls/mbedtls_config.h ، وهو أيضًا المكان الذي يمكن فيه تحديد الميزات. يمكن تحرير هذا الملف يدويًا، أو بطريقة أكثر برمجية باستخدام Python 3 script scripts/config.py (استخدم --help لتعليمات الاستخدام).
يمكن تعيين خيارات المترجم باستخدام متغيرات البيئة التقليدية مثل CC و CFLAGS عند استخدام نظام البناء Make وCMake (انظر أدناه).
نحن نقدم بعض التكوينات غير القياسية التي تركز على حالات استخدام محددة في الدليل configs/ . يمكنك قراءة المزيد عن تلك الموجودة في configs/README.txt
وثائق Mbed TLS الرئيسية متاحة عبر ReadTheDocs.
تتوفر وثائق واجهة برمجة تطبيقات تشفير PSA على GitHub.
لإنشاء نسخة محلية من وثائق المكتبة بتنسيق HTML، مصممة خصيصًا لتكوين وقت الترجمة الخاص بك:
make apidoc .apidoc/index.html أو apidoc/modules.html .للحصول على مصادر أخرى للوثائق، راجع مستند الدعم.
يوجد حاليًا ثلاثة أنظمة بناء نشطة مستخدمة في إصدارات Mbed TLS:
الأنظمة الرئيسية المستخدمة للتطوير هي CMake و GNU Make. وتكون هذه الأنظمة دائمًا كاملة ومحدثة. يجب أن تعكس التغييرات الأخرى جميع التغييرات الموجودة في نظام البناء CMake وMake، على الرغم من أن الميزات قد لا يتم نقلها إلى هناك تلقائيًا.
يقوم نظاما البناء Make وCMake بإنشاء ثلاث مكتبات: libmbedcrypto/libtfpsacrypto، وlimbedx509، وlimbbedtls. لاحظ أن libmbedtls يعتمد على libmbedx509 وlimbedcrypto/libtfpsacrypto، وlimbbedx509 يعتمد على libmbedcrypto/libtfpsacrypto. ونتيجة لذلك، تتوقع بعض الروابط أن تكون العلامات بترتيب معين، على سبيل المثال، يريد رابط GNU -lmbedtls -lmbedx509 -lmbedcrypto .
أنت بحاجة إلى الأدوات التالية لإنشاء المكتبة باستخدام ملفات makefiles المتوفرة:
يستخدم فرع 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 ومترجم C. تتطلب بعض أهداف البناء الأكثر تقدمًا بعض أدوات Unix/Linux.
نحن نستخدم فقط الحد الأدنى من الوظائف في ملفات makefiles عمدًا لإبقائها بسيطة ومستقلة عن سلاسل الأدوات المختلفة قدر الإمكان، للسماح للمستخدمين بالتنقل بسهولة أكبر بين الأنظمة الأساسية المختلفة. يُنصح المستخدمون الذين يحتاجون إلى المزيد من الميزات باستخدام CMake.
من أجل البناء من الكود المصدري باستخدام GNU Make، فقط أدخل في سطر الأوامر:
make
لتشغيل الاختبارات أدخل:
make check
تحتاج الاختبارات إلى إنشاء لغة Python وتشغيل لغة Perl. إذا لم يكن لديك أي منها مثبتًا، فيمكنك تخطي إنشاء الاختبارات باستخدام:
make no_test
سيظل بإمكانك إجراء مجموعة أصغر بكثير من الاختبارات باستخدام:
programs/test/selftest
من أجل إنشاء منصة Windows، يجب عليك استخدام WINDOWS_BUILD=1 إذا كان الهدف هو Windows ولكن بيئة البناء تشبه Unix (على سبيل المثال عند الترجمة المتداخلة، أو الترجمة من MSYS Shell)، و WINDOWS=1 إذا كان بيئة البناء هي Windows Shell (على سبيل المثال باستخدام mingw32-make) (في هذه الحالة لن تكون بعض الأهداف متاحة).
سيؤدي تعيين المتغير SHARED في بيئتك إلى إنشاء مكتبات مشتركة بالإضافة إلى المكتبات الثابتة. يمنحك إعداد DEBUG إنشاء تصحيح الأخطاء. يمكنك تجاوز CFLAGS و LDFLAGS عن طريق تعيينهما في بيئتك أو في سطر أوامر الإنشاء؛ قد يتم تجاوز خيارات تحذير المترجم بشكل منفصل باستخدام WARNING_CFLAGS . لا تزال بعض الخيارات الخاصة بالدليل (على سبيل المثال، توجيهات -I ) محفوظة.
يرجى ملاحظة أن إعداد CFLAGS يتجاوز قيمته الافتراضية -O2 وإعداد WARNING_CFLAGS يتجاوز قيمته الافتراضية (بدءًا بـ -Wall -Wextra )، لذلك إذا كنت تريد فقط إضافة بعض خيارات التحذير إلى الخيارات الافتراضية، فيمكنك القيام بذلك عن طريق تعيين CFLAGS=-O2 -Werror على سبيل المثال. يعد إعداد WARNING_CFLAGS مفيدًا عندما تريد التخلص من محتواه الافتراضي (على سبيل المثال لأن المترجم الخاص بك لا يقبل -Wall كخيار). لا يمكن تجاوز الخيارات الخاصة بالدليل من سطر الأوامر.
اعتمادًا على النظام الأساسي الخاص بك، قد تواجه بعض المشكلات. يرجى التحقق من Makefiles في 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، يقوم هذا الوضع أيضًا بضبط التعليمات البرمجية باستخدام UnifiedSanitizer للتحقق من السلوك غير المحدد.)ASanDbg . مثل Asan ولكنه أبطأ، مع معلومات تصحيح الأخطاء وتتبع المكدس بشكل أفضل.MemSan . يقوم هذا بتجهيز الكود باستخدام MemorySanitizer للتحقق من قراءات الذاكرة غير المهيأة. تجريبي، يحتاج إلى رنة حديثة على 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 وتريد تغيير هذه الإعدادات، فستحتاج إلى إزالة دليل البناء وإنشائه مرة أخرى.
لاحظ أنه من الممكن البناء في المكان؛ ومع ذلك، سيؤدي هذا إلى استبدال ملفات Makefiles المتوفرة (راجع 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 وما يعادلها موقعة متاحة.تعد هندسة أمان النظام الأساسي (PSA) الخاصة بشركة Arm عبارة عن مجموعة شاملة من نماذج التهديدات، والتحليلات الأمنية، ومواصفات بنية الأجهزة والبرامج الثابتة، وتنفيذ مرجعي للبرامج الثابتة مفتوح المصدر. توفر PSA وصفة، بناءً على أفضل ممارسات الصناعة، تسمح بتصميم الأمان بشكل متسق، على مستوى الأجهزة والبرامج الثابتة.
توفر واجهة برمجة تطبيقات تشفير PSA إمكانية الوصول إلى مجموعة من أساسيات التشفير. لها غرض مزدوج. أولاً، يمكن استخدامه في منصة متوافقة مع PSA لإنشاء خدمات، مثل التمهيد الآمن والتخزين الآمن والاتصال الآمن. ثانيًا، يمكن أيضًا استخدامه بشكل مستقل عن مكونات PSA الأخرى على أي منصة.
تتضمن أهداف تصميم واجهة برمجة تطبيقات تشفير PSA ما يلي:
ترحب شركة Arm بالتعليقات حول تصميم واجهة برمجة التطبيقات. إذا كنت تعتقد أنه يمكن تحسين شيء ما، يرجى فتح مشكلة في مستودع Github الخاص بنا. وبدلاً من ذلك، إذا كنت تفضل تقديم تعليقاتك بشكل خاص، فيرجى مراسلتنا عبر البريد الإلكتروني على [email protected] . يتم التعامل مع جميع التعليقات الواردة عبر البريد الإلكتروني بسرية.
يتضمن Mbed TLS تطبيقًا مرجعيًا لـ PSA Cryptography API. ومع ذلك، فإنه لا يهدف إلى تنفيذ المواصفات بأكملها؛ على وجه الخصوص، لا ينفذ جميع الخوارزميات.
يمكن لرمز 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 أو إصدار أحدث. راجع ملف الترخيص للحصول على النص الكامل لهذه التراخيص، وقسم "الترخيص وحقوق النشر" في إرشادات المساهمة لمزيد من المعلومات.
يحتوي هذا المشروع على تعليمات برمجية من مشاريع أخرى. يوجد هذا الرمز داخل دليل tf-psa-crypto/drivers/ . يتم تضمين نص الترخيص الأصلي ضمن الدلائل الفرعية للمشروع، حيث يختلف عن ترخيص Mbed TLS العادي، و/أو في الملفات المصدر. المشاريع مذكورة أدناه:
drivers/everest/ : الملفات تنبع من مشروع 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.
