Быстрая, портативная и легковесная реализация COSE + CBOR для встраиваемых систем. Поддерживает PQC, FIPS 140-3, DO-178 и MISRA C. Работает на базе wolfSSL.
# wolfCOSE
wolfCOSE — это легковесная и быстрая библиотека на C, реализующая основные стандарты CBOR и COSE, с криптографической поддержкой на базе [wolfSSL](https://github.com/wolfSSL/wolfssl).
## Поддерживаемые стандарты и RFC
* **Основные спецификации:**
* [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) — Concise Binary Object Representation (CBOR)
* [RFC 9052](https://www.rfc-editor.org/rfc/rfc9052) — CBOR Object Signing and Encryption (COSE)
* [RFC 9053](https://www.rfc-editor.org/rfc/rfc9053) — алгоритмы COSE
* [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864) — Fully-Specified Algorithms for JOSE and COSE
* [RFC 9338](https://www.rfc-editor.org/rfc/rfc9338) — COSE Countersignatures
* **Постквантовая криптография:**
* [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 Attestation Token Profile of EAT
## Основные возможности
* **Полный набор COSE (RFC 9052):** Полная поддержка всех шести типов сообщений, включая `COSE_Sign1`, `COSE_Encrypt0` и `COSE_Mac0`.
* **Countersignatures V2 (RFC 9338):** Полные и сокращённые встроенные countersignatures для всех шести типизированных типов сообщений COSE.
* **Постквантовая криптография:**
* ML-DSA (FIPS 204 / RFC 9964) на всех уровнях безопасности.
* HSS/LMS — stateful hash-based подпись (RFC 8778 / CNSA 2.0).
* **Высокая производительность:** На Intel i9-11950H сквозной `COSE_Sign1` достигает 66 538 sign/s и 26 437 verify/s с ES256, а также 21 986 sign/s и 53 686 verify/s с ML-DSA-44. См. [детали производительности и размера](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) и [wolfCOSE vs. The Field](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 Attestation:** Выпуск и проверка EAT / PSA Token с поддержкой делегированной подписи через HSM.
* **41 криптографический алгоритм:** Широкий охват алгоритмов для подписи, шифрования, MAC и распределения ключей.
* **Дизайн для встраиваемых систем:** Нулевое динамическое выделение памяти (без кучи, ноль `.data`/`.bss`). Работа с буферами, предоставляемыми вызывающей стороной, с ограниченным использованием стека.
* **Путь к FIPS 140-3:** Использует wolfCrypt (FIPS Certificate #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`
* **Stateful Hash-Based:** `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` | Сериализация ключей для всех типов ключей |
Countersignatures из RFC 9338 могут быть прикреплены к любому типизированному
сообщению из этой таблицы. Используйте `wc_Cose_AddCounterSignature()` или
`wc_Cose_AddCounterSignature0()` для добавления, затем проверяйте её независимо
с помощью соответствующего API `wc_Cose_VerifyCounterSignature*()`.
## Зависимости (wolfSSL)
wolfCOSE требует [wolfSSL](https://www.wolfssl.com/) в качестве криптографического бэкенда.
**Минимальная поддерживаемая версия: v5.8.0-stable**. Некоторые опциональные алгоритмы требуют
более новых релизов; см. [Getting Started](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
```
См. [Tuning for Size](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-size) и [Tuning for Speed](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)
для дальнейшей оптимизации wolfCOSE и wolfCrypt на MCU.
### Минимальная сборка (только постквантовая / 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`. API
`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` для constrained-целей |
| `make eat-psa-config-check` | Проверить, что PSA/EAT отсутствует по умолчанию, и провалидировать комбинации feature-gate |
| `make psa-eat-lean-verify` | Собрать + запустить полный пример проверки RFC-векторов PSA/EAT `#tfm` в режиме verify-only |
| `make psa-eat-demo` | Выпустить, проверить и оценить актуальный токен онбординга устройства RFC 9783 |
| `make tool` | Собрать CLI-инструмент (`tools/wolfcose_tool`) |
| `make tool-test` | Round-trip самотестирование для всех 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 в lean-сборке
## CI / Тестирование
Запускается на каждый push и PR:
- **Сборка + тесты**: Ubuntu, macOS, GCC 10-14, Clang 14-18
- **Комплексные тесты**: ~240 тестов комбинаций алгоритмов
- **Статический анализ**: cppcheck, Clang analyzer, GCC `-fanalyzer`
- **MISRA C 2012**: cppcheck `--addon=misra` проверяет все пути кода wolfCOSE
- **MISRA C 2023**: строгие предупреждения GCC и clang-tidy (`bugprone-*`, `cert-*`, `clang-analyzer-*`, `misc-*`)
- **Coverity Scan**: ночной анализ дефектов
- **Внутренний статический анализ:** Fenrir wolfssl advanced static analysis tools
- **Покрытие кода**: 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):
- [Getting Started](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html): инструкции по сборке и первые шаги
- [Message Types](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html): все шесть сообщений RFC 9052 (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) и countersignatures RFC 9338 с примерами кода
- [Algorithms](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html): полный список 41 поддерживаемого алгоритма с COSE ID
- [API Reference](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html): сигнатуры функций, структуры данных, коды ошибок
- [Macros](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html): конфигурация времени компиляции, оптимизация размера и политика ECDSA nonce
- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html): профили токенов PSA RFC 9783, API, макросы и рекомендации по безопасности
- [Footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html): показатели размера и скорости, на десктопе и на устройстве
- [Testing](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html): инфраструктура тестирования, покрытие и инъекция сбоев
- [MISRA Compliance](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html): статус соответствия MISRA C:2012 и C:2023 и обоснование отклонений
- [Project Structure](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), countersignatures 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).
Copyright (C) 2026 wolfSSL Inc.
## Поддержка
Для коммерческого лицензирования, договоров профессиональной поддержки или обсуждения внедрения wolfCOSE в вашу производственную среду свяжитесь с [wolfSSL](https://www.wolfssl.com/contact/).