تطبيق سريع، محمول، وخفيف الوزن لـ COSE + CBOR للأنظمة المضمنة. يدعم PQC، FIPS 140-3، DO-178، وMISRA C. مدعوم من wolfSSL.
# wolfCOSE
wolfCOSE هي مكتبة C خفيفة وسريعة تنفذ معايير CBOR وCOSE الأساسية، مدعومة بـ [wolfSSL](https://github.com/wolfSSL/wolfssl) للتشفير.
## المعايير و RFCs المدعومة
* **المواصفات الأساسية:**
* [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) - تمثيل الكائنات الثنائية المختصرة (CBOR)
* [RFC 9052](https://www.rfc-editor.org/rfc/rfc9052) - توقيع وتشفير كائنات CBOR (COSE)
* [RFC 9053](https://www.rfc-editor.org/rfc/rfc9053) - خوارزميات COSE
* [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864) - الخوارزميات محددة بالكامل لـ JOSE و COSE
* [RFC 9338](https://www.rfc-editor.org/rfc/rfc9338) - التوقيعات المضادة لـ COSE
* **التشفير ما بعد الكمي:**
* [RFC 9964](https://www.rfc-editor.org/rfc/rfc9964) - ML-DSA لـ COSE
* [RFC 8778](https://www.rfc-editor.org/rfc/rfc8778) - HSS/LMS لـ COSE
* **الإثبات:**
* [RFC 9783](https://www.rfc-editor.org/rfc/rfc9783) - ملف رمز إثبات PSA الخاص بـ EAT
## الميزات الرئيسية
* **مجموعة COSE الكاملة (RFC 9052):** دعم كامل لجميع أنواع الرسائل الستة، بما في ذلك `COSE_Sign1` و `COSE_Encrypt0` و `COSE_Mac0`.
* **التوقيعات المضادة V2 (RFC 9338):** توقيعات مضادة كاملة ومختصرة في المكان عبر جميع أنواع رسائل COSE الستة الموسومة.
* **التشفير ما بعد الكمي:**
* ML-DSA (FIPS 204 / RFC 9964) في جميع مستويات الأمان.
* توقيع HSS/LMS القائم على التجزئة ذو الحالة (RFC 8778 / CNSA 2.0).
* **أداء سريع:** على معالج Intel i9-11950H، يصل `COSE_Sign1` من البداية إلى النهاية إلى 66,538 توقيع/ثانية و 26,437 تحقق/ثانية مع ES256، و 21,986 توقيع/ثانية و 53,686 تحقق/ثانية مع ML-DSA-44. راجع [تفاصيل الأداء والبصمة](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) و [wolfCOSE مقابل المنافسين](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/).
* **إثبات PSA:** إصدار والتحقق من رمز EAT / PSA مع دعم التوقيع المفوّض عبر HSM.
* **41 خوارزمية تشفير:** تغطية واسعة للخوارزميات عبر التوقيع والتشفير و MAC وتوزيع المفاتيح.
* **تصميم موجه للأنظمة المدمجة:** صفر تخصيص ذاكرة ديناميكية (لا heap، صفر `.data`/`.bss`). يعمل على المخازن المؤقتة التي يوفرها المستدعي مع استخدام محدود للمكدس.
* **مسار FIPS 140-3:** يستخدم wolfCrypt (شهادة FIPS رقم 4718) كاعتماده التشفيري الوحيد.
* **متكامل مع STM32:** حزمة STM32Cube جاهزة (`I-CUBE-wolfCOSE`) متاحة لـ STM32CubeMX / IDE ([التفاصيل](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html)).
## الخوارزميات المدعومة
* **التوقيعات الرقمية:**
* **الكلاسيكية:** `ESP256`، `ESP384`، `ESP512`، `Ed25519`، `Ed448`، `PS256`، `PS384`، `PS512`
* **ما بعد الكمية:** `ML-DSA-44`، `ML-DSA-65`، `ML-DSA-87`
* **القائمة على التجزئة ذات الحالة:** `HSS-LMS`
* **التشفير (AEAD):**
* `AES-GCM` (128 / 192 / 256)
* `AES-CCM` (متغيرات)
* `ChaCha20-Poly1305`
* **مصادقة الرسائل (MAC):**
* `HMAC-SHA256`، `HMAC-SHA384`، `HMAC-SHA512`
* `AES-MAC`
* **توزيع المفاتيح:**
* `Direct`
* `AES Key Wrap`
* `ECDH-ES + HKDF`
## أنواع رسائل COSE (RFC 9052)
نفذت wolfCOSE جميع رسائل RFC 9052 بنسختيها أحادية الفاعل ومتعددة الفاعلين:
| الرسالة | RFC 9052 | API | الغرض |
|---|---|---|---|
| `COSE_Sign1` | Sec. 4.2 | `wc_CoseSign1_Sign` / `wc_CoseSign1_Verify` | توقيع موقّع واحد |
| `COSE_Sign` | Sec. 4.1 | `wc_CoseSign_Sign` / `wc_CoseSign_Verify` | **متعدد الموقّعين** (توقيعات مستقلة على نفس الحمولة) |
| `COSE_Encrypt0` | Sec. 5.2 | `wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt` | AEAD لمستلم واحد |
| `COSE_Encrypt` | Sec. 5.1 | `wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt` | **متعدد المستلمين** (نص مشفر واحد، مستلمون متعددون عبر Direct / AES-KW / ECDH-ES) |
| `COSE_Mac0` | Sec. 6.2 | `wc_CoseMac0_Create` / `wc_CoseMac0_Verify` | MAC لمستلم واحد |
| `COSE_Mac` | Sec. 6.1 | `wc_CoseMac_Create` / `wc_CoseMac_Verify` | MAC **متعدد المستلمين** (مفتاح MAC مشترك، موزع على المستلمين) |
| `COSE_Key` / `COSE_KeySet` | Sec. 7 | `wc_CoseKey_Encode` / `wc_CoseKey_Decode` | تسلسل المفاتيح لجميع أنواع المفاتيح |
يمكن إرفاق التوقيعات المضادة من RFC 9338 بأي رسالة موسومة في هذا
الجدول. استخدم `wc_Cose_AddCounterSignature()` أو
`wc_Cose_AddCounterSignature0()` لإضافة واحدة، ثم تحقق منها بشكل مستقل
باستخدام واجهة `wc_Cose_VerifyCounterSignature*()` المقابلة.
## التبعيات (wolfSSL)
تتطلب wolfCOSE مكتبة [wolfSSL](https://www.wolfssl.com/) كخلفية تشفيرية لها.
**الحد الأدنى للإصدار المدعوم: v5.8.0-stable**. تتطلب بعض الخوارزميات الاختيارية
إصدارات أحدث؛ راجع [بدء الاستخدام](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html#prerequisites) للاطلاع على
الحدود الدنيا للتبعيات الخاصة بكل ميزة وتعليمات البناء. يتطلب HSS/LMS (RFC 8778)
الإصدار v5.9.2-stable أو أحدث.
اختر تكوين بناء بناءً على الخوارزميات التي تحتاجها.
### بناء أدنى (ECC + AES-GCM)
يمنحك هذا COSE Sign1 (ESP256/384/512) و Encrypt0 (AES-GCM):
```bash
cd wolfssl
./autogen.sh
./configure --enable-ecc --enable-aesgcm \
--enable-sha384 --enable-sha512 --enable-keygen
make && sudo make install
sudo ldconfig
```
**الخوارزميات المفعّلة:** ESP256، ESP384، ESP512، AES-GCM-128/192/256
لبصمة أصغر لـ wolfCrypt، أضف `--enable-cryptonly` لإسقاط حزمة TLS
وتعطيل الخوارزميات التي لا يستخدمها بناء Sign1 + Encrypt0 أبدًا:
```bash
./configure --enable-cryptonly --enable-ecc --enable-aesgcm \
--enable-sha384 --enable-sha512 --enable-keygen \
--enable-lowresource \
--disable-dh --disable-rsa --disable-aescbc \
--disable-sha --disable-md5 --disable-chacha --disable-poly1305 \
--disable-errorstrings
```
راجع [الضبط من أجل الحجم](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-size) و [الضبط من أجل السرعة](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)
لتقليص حجم wolfCOSE و wolfCrypt بشكل أكبر على وحدات التحكم الدقيقة.
### بناء أدنى (ما بعد الكمي / ML-DSA فقط)
للتوقيع ما بعد الكمي الخالص باستخدام ML-DSA-44/65/87:
```bash
cd wolfssl
./autogen.sh
./configure --enable-cryptonly --enable-mldsa
make && sudo make install
sudo ldconfig
```
**الخوارزميات المفعّلة:** ML-DSA-44، ML-DSA-65، ML-DSA-87
(يتم تضمين SHAKE-128/256 تلقائيًا بواسطة `--enable-mldsa`. تتطلب
واجهة `wc_MlDsaKey` إصدار wolfSSL أحدث من v5.9.1-stable.)
### بناء كامل (جميع الخوارزميات)
```bash
cd wolfssl
./autogen.sh
./configure --enable-ecc --enable-ed25519 --enable-ed448 \
--enable-curve25519 --enable-aesgcm --enable-aesccm \
--enable-sha384 --enable-sha512 --enable-keygen \
--enable-rsapss --enable-chacha --enable-poly1305 \
--enable-mldsa --enable-lms \
--enable-hkdf --enable-aeskeywrap
make && sudo make install
sudo ldconfig
```
## البناء
```bash
# Core library (libwolfcose.a)
make
# Run unit tests
make test
# Build and run CLI tool round-trip tests (all algorithms)
make tool-test
# Run lifecycle demo (11 algorithms)
make demo
```
### أهداف البناء
| الهدف | الوصف |
|--------|-------------|
| `make all` | بناء `libwolfcose.a` (المكتبة الأساسية فقط) |
| `make shared` | بناء `libwolfcose.so` |
| `make test` | بناء + تشغيل اختبارات وحدة CBOR و COSE |
| `make pkg-config-test` | التحقق من اكتشاف حزمة wolfSSL والتجاوزات |
| `make eat-psa-test` | بناء + تشغيل مجموعة مطابقة RFC 9783 PSA/EAT الكاملة الصريحة |
| `make eat-psa-min-buffers-test` | تشغيل مجموعة PSA/EAT الكاملة مع حدود `WOLFCOSE_MIN_BUFFERS` للأهداف المقيدة |
| `make eat-psa-config-check` | التحقق من غياب PSA/EAT افتراضيًا والتحقق من تركيبات بوابات الميزات |
| `make psa-eat-lean-verify` | بناء + تشغيل مثال التحقق فقط `#tfm` الكامل لمتجه RFC الخاص بـ PSA/EAT |
| `make psa-eat-demo` | إصدار والتحقق وتقييم رمز تسجيل جهاز RFC 9783 الحالي |
| `make tool` | بناء أداة CLI (`tools/wolfcose_tool`) |
| `make tool-test` | اختبار ذاتي ذهاب وإياب لجميع الخوارزميات الـ 17 |
| `make demo` | بناء + تشغيل عرض دورة الحياة (11 خوارزمية) |
| `make clean` | إزالة جميع مخرجات البناء |
## بدء سريع
### الأمثلة
راجع `examples/` للحصول على كود عامل كامل:
- `sign1_demo.c`، `encrypt0_demo.c`، `mac0_demo.c`: عروض توضيحية للخوارزميات
- `lifecycle_demo.c`: سير عمل كامل من الحافة إلى السحابة
- `comprehensive/`: اختبارات مصفوفة الخوارزميات
- `scenarios/`: توقيع البرامج الثابتة، الإثبات، تكوين الأسطول
- `psa_eat_demo.c`: تسجيل جهاز RFC 9783 مع تقييم القياسات
- `psa_eat_verify_lean.c`: التحقق من Sign1 للملف الشخصي الحالي RFC 9783 في بناء خفيف
## CI / الاختبار
يعمل عند كل دفعة و PR:
- **البناء + الاختبار**: Ubuntu، macOS، GCC 10-14، Clang 14-18
- **اختبارات شاملة**: ~240 اختبار تركيبة خوارزميات
- **التحليل الساكن**: cppcheck، محلل Clang، GCC `-fanalyzer`
- **MISRA C 2012**: cppcheck `--addon=misra` يفحص جميع مسارات كود wolfCOSE
- **MISRA C 2023**: تحذيرات GCC الصارمة و clang-tidy (`bugprone-*`، `cert-*`، `clang-analyzer-*`، `misc-*`)
- **Coverity Scan**: تحليل العيوب الليلي
- **التحليل الساكن الداخلي:** أدوات التحليل الساكن المتقدمة Fenrir wolfssl
- **تغطية الكود**: تغطية أسطر 100% مفروضة لكل ملف مصدري في wolfCOSE
```bash
make coverage # Run tests with gcov
make coverage-force-failure # Include crypto failure path testing
```
<a href="https://scan.coverity.com/projects/wolfcose">
<img alt="Coverity Scan Build Status"
src="https://scan.coverity.com/projects/32918/badge.svg"/>
</a>
<a href="https://github.com/wolfSSL/wolfCOSE/actions">
<img alt="CI Status"
src="https://img.shields.io/github/actions/workflow/status/wolfSSL/wolfCOSE/build-test.yml?label=CI&logo=github"/>
</a>
## التوثيق
يُنشر دليل wolfCOSE الرسمي على
[wolfssl.com/documentation/manuals/wolfcose](https://www.wolfssl.com/documentation/manuals/wolfcose/index.html):
- [بدء الاستخدام](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html): تعليمات البناء والخطوات الأولى
- [أنواع الرسائل](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html): جميع رسائل RFC 9052 الستة (Sign1، Sign، Encrypt0، Encrypt، Mac0، Mac) والتوقيعات المضادة من RFC 9338 مع أمثلة كود
- [الخوارزميات](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html): قائمة كاملة بالخوارزميات الـ 41 المدعومة مع معرفات COSE
- [مرجع API](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html): توقيعات الدوال، هياكل البيانات، رموز الأخطاء
- [الماكرو](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html): تكوين وقت الترجمة، ضبط الحجم، وسياسة nonce لـ ECDSA
- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html): ملفات رمز PSA من RFC 9783، واجهات API، الماكرو، وإرشادات الأمان
- [البصمة](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html): أرقام الحجم والسرعة، على سطح المكتب وعلى الجهاز
- [الاختبار](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html): البنية التحتية للاختبار، التغطية، وحقن الأخطاء
- [الامتثال لـ MISRA](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html): حالة الامتثال لـ MISRA C:2012 و C:2023 ومبررات الانحراف
- [هيكل المشروع](https://www.wolfssl.com/documentation/manuals/wolfcose/Project-Structure.html): تخطيط الملفات المصدرية
- [STM32Cube](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html): تثبيت وتشغيل wolfCOSE كحزمة STM32Cube على الجهاز
توجد مصادر الدليل في [`docs/`](https://github.com/wolfssl/wolfcose/blob/main/docs)؛ يحدد `mkdocs.yml` التنقل
وتبني أدوات [`wolfSSL/documentation`](https://github.com/wolfSSL/documentation) المشتركة
ملفات HTML و PDF. راجع [docs/dev/DOCS-BUILD.md](https://github.com/wolfssl/wolfcose/blob/main/docs/dev/DOCS-BUILD.md)
للمعاينات المحلية وكيفية وصول التغييرات إلى الموقع.
## ملاحظات الإصدار
الإصدار الحالي هو **2.0.0**. يضيف توقيعات HSS/LMS الموحدة (RFC 8778)، والتوقيعات المضادة لـ COSE (RFC 9338)، وإثبات PSA/EAT (RFC 9783)، ومعرفات التوقيع RFC 9864، والتوقيع المفوّض، وواجهات API موسعة للمفاتيح و CBOR، و COSE-HPKE التجريبي، وتقوية واسعة النطاق، كل ذلك بدون أي تخصيص ديناميكي. راجع [ChangeLog.md](https://github.com/wolfssl/wolfcose/blob/main/ChangeLog.md) للحصول على ملاحظات الإصدار الكاملة.
تم تطوير wolfCOSE 2.0.0 وفقًا لعملية التطوير وضمان الجودة لدى wolfSSL (راجع https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance) واجتاز معايير الجودة بنجاح.
## الترخيص
wolfCOSE برنامج حر مرخص بموجب [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html)؛ راجع [LICENSE](https://github.com/wolfssl/wolfcose/blob/main/LICENSE) للنص الكامل.
حقوق النشر (C) 2026 wolfSSL Inc.
## الدعم
للترخيص التجاري، أو عقود الدعم الاحترافي، أو لمناقشة نقل wolfCOSE إلى بيئة الإنتاج الخاصة بك، اتصل بـ [wolfSSL](https://www.wolfssl.com/contact/).