wolfCOSE

wolfCOSE هي مكتبة C خفيفة وسريعة تنفذ معايير CBOR وCOSE الأساسية، مدعومة بـ wolfSSL للتشفير.

المعايير و RFCs المدعومة

• المواصفات الأساسية:
  • RFC 8949 - تمثيل الكائنات الثنائية المختصرة (CBOR)
  • RFC 9052 - توقيع وتشفير كائنات CBOR (COSE)
  • RFC 9053 - خوارزميات COSE
  • RFC 9864 - الخوارزميات محددة بالكامل لـ JOSE و COSE
  • RFC 9338 - التوقيعات المضادة لـ COSE
• التشفير ما بعد الكمي:
  • RFC 9964 - ML-DSA لـ COSE
  • RFC 8778 - HSS/LMS لـ COSE
• الإثبات:
  • RFC 9783 - ملف رمز إثبات 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. راجع تفاصيل الأداء والبصمة و wolfCOSE مقابل المنافسين.
• إثبات PSA: إصدار والتحقق من رمز EAT / PSA مع دعم التوقيع المفوّض عبر HSM.
• 41 خوارزمية تشفير: تغطية واسعة للخوارزميات عبر التوقيع والتشفير و MAC وتوزيع المفاتيح.
• تصميم موجه للأنظمة المدمجة: صفر تخصيص ذاكرة ديناميكية (لا heap، صفر .data/.bss). يعمل على المخازن المؤقتة التي يوفرها المستدعي مع استخدام محدود للمكدس.
• مسار FIPS 140-3: يستخدم wolfCrypt (شهادة FIPS رقم 4718) كاعتماده التشفيري الوحيد.
• متكامل مع STM32: حزمة STM32Cube جاهزة (I-CUBE-wolfCOSE) متاحة لـ STM32CubeMX / IDE (التفاصيل).

الخوارزميات المدعومة

• التوقيعات الرقمية:
  • الكلاسيكية: 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 كخلفية تشفيرية لها. الحد الأدنى للإصدار المدعوم: v5.8.0-stable. تتطلب بعض الخوارزميات الاختيارية إصدارات أحدث؛ راجع بدء الاستخدام للاطلاع على الحدود الدنيا للتبعيات الخاصة بكل ميزة وتعليمات البناء. يتطلب HSS/LMS (RFC 8778) الإصدار v5.9.2-stable أو أحدث.

اختر تكوين بناء بناءً على الخوارزميات التي تحتاجها.

بناء أدنى (ECC + AES-GCM)

يمنحك هذا COSE Sign1 (ESP256/384/512) و Encrypt0 (AES-GCM):

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 أبدًا:

./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

راجع الضبط من أجل الحجم و الضبط من أجل السرعة لتقليص حجم wolfCOSE و wolfCrypt بشكل أكبر على وحدات التحكم الدقيقة.

بناء أدنى (ما بعد الكمي / ML-DSA فقط)

للتوقيع ما بعد الكمي الخالص باستخدام ML-DSA-44/65/87:

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.)

بناء كامل (جميع الخوارزميات)

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

البناء

# 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	إزالة جميع مخرجات البناء

بدء سريع

الأمثلة