
Una implementación rápida, portátil y ligera de COSE + CBOR para sistemas embebidos. Admite PQC, FIPS 140-3, DO-178 y MISRA C. Desarrollado por wolfSSL.
# wolfCOSE
wolfCOSE es una biblioteca C ligera y rápida que implementa los estándares básicos CBOR y COSE, respaldada por [wolfSSL](https://github.com/wolfSSL/wolfssl) para criptografía.
## Estándares y RFC compatibles
* **Especificaciones principales:**
* [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) - Algoritmos 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
* **Criptografía post-cuántica:**
* [RFC 9964](https://www.rfc-editor.org/rfc/rfc9964) - ML-DSA para COSE
* [RFC 8778](https://www.rfc-editor.org/rfc/rfc8778) - HSS/LMS para COSE
* **Atestación:**
* [RFC 9783](https://www.rfc-editor.org/rfc/rfc9783) - PSA Attestation Token Profile of EAT
## Características principales
* **Suite COSE completa (RFC 9052):** Soporte completo para los seis tipos de mensaje, incluidos `COSE_Sign1`, `COSE_Encrypt0` y `COSE_Mac0`.
* **Contrafirmas V2 (RFC 9338):** Contrafirmas in-place completas y abreviadas en los seis tipos de mensaje COSE etiquetados.
* **Criptografía post-cuántica:**
* ML-DSA (FIPS 204 / RFC 9964) en todos los niveles de seguridad.
* Firma con hash con estado HSS/LMS (RFC 8778 / CNSA 2.0).
* **Rendimiento rápido:** En un Intel i9-11950H, `COSE_Sign1` de extremo a extremo alcanza 66.538 firmas/s y 26.437 verificaciones/s con ES256, y 21.986 firmas/s y 53.686 verificaciones/s con ML-DSA-44. Consulte los [detalles de rendimiento y huella](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) y [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/).
* **Atestación PSA:** Emisión y verificación de tokens EAT / PSA con soporte de firma HSM delegada.
* **41 algoritmos criptográficos:** Amplia cobertura de algoritmos en firma, cifrado, MAC y distribución de claves.
* **Diseño orientado a sistemas embebidos:** Cero asignación dinámica de memoria (sin heap, cero `.data`/`.bss`). Opera sobre búferes proporcionados por el llamador con uso de pila acotado.
* **Ruta FIPS 140-3:** Utiliza wolfCrypt (Certificado FIPS #4718) como su única dependencia criptográfica.
* **Integrado con STM32:** Paquete STM32Cube listo para usar (`I-CUBE-wolfCOSE`) disponible para STM32CubeMX / IDE ([Detalles](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html)).
## Algoritmos compatibles
* **Firmas digitales:**
* **Clásicos:** `ESP256`, `ESP384`, `ESP512`, `Ed25519`, `Ed448`, `PS256`, `PS384`, `PS512`
* **Post-cuánticos:** `ML-DSA-44`, `ML-DSA-65`, `ML-DSA-87`
* **Hash con estado:** `HSS-LMS`
* **Cifrado (AEAD):**
* `AES-GCM` (128 / 192 / 256)
* `AES-CCM` (variantes)
* `ChaCha20-Poly1305`
* **Autenticación de mensajes (MAC):**
* `HMAC-SHA256`, `HMAC-SHA384`, `HMAC-SHA512`
* `AES-MAC`
* **Distribución de claves:**
* `Direct`
* `AES Key Wrap`
* `ECDH-ES + HKDF`
## Tipos de mensaje COSE (RFC 9052)
wolfCOSE ha implementado todos los mensajes del RFC 9052 tanto en variantes de un solo actor como multi-actor:
| Mensaje | RFC 9052 | API | Propósito |
|---|---|---|---|
| `COSE_Sign1` | Sec. 4.2 | `wc_CoseSign1_Sign` / `wc_CoseSign1_Verify` | Firma de un solo firmante |
| `COSE_Sign` | Sec. 4.1 | `wc_CoseSign_Sign` / `wc_CoseSign_Verify` | **Multi-firmante** (firmas independientes sobre el mismo payload) |
| `COSE_Encrypt0` | Sec. 5.2 | `wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt` | AEAD de un solo destinatario |
| `COSE_Encrypt` | Sec. 5.1 | `wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt` | **Multi-destinatario** (un ciphertext, muchos destinatarios vía Direct / AES-KW / ECDH-ES) |
| `COSE_Mac0` | Sec. 6.2 | `wc_CoseMac0_Create` / `wc_CoseMac0_Verify` | MAC de un solo destinatario |
| `COSE_Mac` | Sec. 6.1 | `wc_CoseMac_Create` / `wc_CoseMac_Verify` | MAC **multi-destinatario** (clave MAC compartida, distribuida a los destinatarios) |
| `COSE_Key` / `COSE_KeySet` | Sec. 7 | `wc_CoseKey_Encode` / `wc_CoseKey_Decode` | Serialización de claves para todos los tipos de clave |
Las contrafirmas del RFC 9338 se pueden adjuntar a cualquier mensaje etiquetado en esta
tabla. Use `wc_Cose_AddCounterSignature()` o
`wc_Cose_AddCounterSignature0()` para añadir una, y luego verifíquela de forma independiente con
la API correspondiente `wc_Cose_VerifyCounterSignature*()`.
## Dependencias (wolfSSL)
wolfCOSE requiere [wolfSSL](https://www.wolfssl.com/) como su backend criptográfico.
**Versión mínima compatible: v5.8.0-stable**. Algunos algoritmos opcionales requieren
versiones más recientes; consulte [Getting Started](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html#prerequisites) para
los mínimos de dependencia específicos de cada característica y las instrucciones de compilación. HSS/LMS (RFC 8778)
requiere v5.9.2-stable o posterior.
Elija una configuración de compilación según los algoritmos que necesite.
### Compilación mínima (ECC + AES-GCM)
Esto le proporciona COSE Sign1 (ESP256/384/512) y 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
```
**Algoritmos habilitados:** ESP256, ESP384, ESP512, AES-GCM-128/192/256
Para una huella de wolfCrypt más pequeña, añada `--enable-cryptonly` para eliminar la pila
TLS y deshabilitar los algoritmos que una compilación de Sign1 + Encrypt0 nunca usa:
```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
```
Consulte [Tuning for Size](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-size) y [Tuning for Speed](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)
para reducir aún más wolfCOSE y wolfCrypt en MCUs.
### Compilación mínima (solo post-cuántica / ML-DSA)
Para firma puramente post-cuántica con ML-DSA-44/65/87:
```bash
cd wolfssl
./autogen.sh
./configure --enable-cryptonly --enable-mldsa
make && sudo make install
sudo ldconfig
```
**Algoritmos habilitados:** ML-DSA-44, ML-DSA-65, ML-DSA-87
(SHAKE-128/256 se incluyen automáticamente con `--enable-mldsa`. La
API `wc_MlDsaKey` requiere wolfSSL más reciente que v5.9.1-stable.)
### Compilación completa (todos los algoritmos)
```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
```
## Compilación
```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
```
### Objetivos de compilación
| Objetivo | Descripción |
|--------|-------------|
| `make all` | Compila `libwolfcose.a` (solo la biblioteca principal) |
| `make shared` | Compila `libwolfcose.so` |
| `make test` | Compila y ejecuta las pruebas unitarias de CBOR y COSE |
| `make pkg-config-test` | Verifica el descubrimiento del paquete wolfSSL y las anulaciones |
| `make eat-psa-test` | Compila y ejecuta la suite de conformidad explícita completa RFC 9783 PSA/EAT |
| `make eat-psa-min-buffers-test` | Ejecuta la suite completa PSA/EAT con los límites de objetivo restringido `WOLFCOSE_MIN_BUFFERS` |
| `make eat-psa-config-check` | Verifica que PSA/EAT está ausente por defecto y valida las combinaciones de feature-gate |
| `make psa-eat-lean-verify` | Compila y ejecuta el ejemplo completo de vectores RFC de verificación PSA/EAT `#tfm` |
| `make psa-eat-demo` | Emite, verifica y evalúa un token de incorporación de dispositivos RFC 9783 actual |
| `make tool` | Compila la herramienta CLI (`tools/wolfcose_tool`) |
| `make tool-test` | Autoprueba de ida y vuelta para los 17 algoritmos |
| `make demo` | Compila y ejecuta la demo del ciclo de vida (11 algoritmos) |
| `make clean` | Elimina todos los artefactos de compilación |
## Inicio rápido
### Ejemplos
Consulte `examples/` para código funcional completo:
- `sign1_demo.c`, `encrypt0_demo.c`, `mac0_demo.c`: demos de algoritmos
- `lifecycle_demo.c`: flujo de trabajo completo de borde a nube
- `comprehensive/`: pruebas de matriz de algoritmos
- `scenarios/`: firma de firmware, atestación, configuración de flota
- `psa_eat_demo.c`: incorporación de dispositivos RFC 9783 con evaluación de mediciones
- `psa_eat_verify_lean.c`: verificación Sign1 del perfil actual RFC 9783 en una compilación ligera
## CI / Pruebas
Se ejecuta en cada push y PR:
- **Compilación + Pruebas**: Ubuntu, macOS, GCC 10-14, Clang 14-18
- **Pruebas exhaustivas**: ~240 pruebas de combinaciones de algoritmos
- **Análisis estático**: cppcheck, Clang analyzer, GCC `-fanalyzer`
- **MISRA C 2012**: cppcheck `--addon=misra` verificando todas las rutas de código de wolfCOSE
- **MISRA C 2023**: advertencias estrictas de GCC y clang-tidy (`bugprone-*`, `cert-*`, `clang-analyzer-*`, `misc-*`)
- **Coverity Scan**: análisis nocturno de defectos
- **Análisis estático interno:** herramientas avanzadas de análisis estático Fenrir wolfssl
- **Cobertura de código**: 100% de cobertura de líneas exigida para cada archivo fuente de 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>
## Documentación
El manual oficial de wolfCOSE se publica en
[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): Instrucciones de compilación y primeros pasos
- [Message Types](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html): Los seis mensajes del RFC 9052 (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) y contrafirmas del RFC 9338 con ejemplos de código
- [Algorithms](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html): Lista completa de los 41 algoritmos compatibles con IDs COSE
- [API Reference](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html): Firmas de funciones, estructuras de datos, códigos de error
- [Macros](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html): Configuración en tiempo de compilación, ajuste de tamaño y política de nonce ECDSA
- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html): Perfiles de token PSA RFC 9783, APIs, macros y guía de seguridad
- [Footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html): Cifras de tamaño y velocidad, en escritorio y en dispositivo
- [Testing](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html): Infraestructura de pruebas, cobertura e inyección de fallos
- [MISRA Compliance](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html): Estado de cumplimiento de MISRA C:2012 y C:2023 y justificación de desviaciones
- [Project Structure](https://www.wolfssl.com/documentation/manuals/wolfcose/Project-Structure.html): Diseño de archivos fuente
- [STM32Cube](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html): Instalar y ejecutar wolfCOSE como paquete STM32Cube en el dispositivo
Las fuentes del manual se encuentran en [`docs/`](https://github.com/wolfssl/wolfcose/blob/main/docs); `mkdocs.yml` define la navegación
y las herramientas compartidas de [`wolfSSL/documentation`](https://github.com/wolfSSL/documentation)
generan el HTML y el PDF. Consulte [docs/dev/DOCS-BUILD.md](https://github.com/wolfssl/wolfcose/blob/main/docs/dev/DOCS-BUILD.md)
para vistas previas locales y cómo los cambios llegan al sitio web.
## Notas de la versión
La versión actual es la **2.0.0**. Añade firmas HSS/LMS estandarizadas (RFC 8778), contrafirmas COSE (RFC 9338), atestación PSA/EAT (RFC 9783), IDs de firma RFC 9864, firma delegada, APIs ampliadas de claves y CBOR, COSE-HPKE experimental y un extenso endurecimiento, todo con cero asignación dinámica. Consulte [ChangeLog.md](https://github.com/wolfssl/wolfcose/blob/main/ChangeLog.md) para las notas de la versión completas.
wolfCOSE 2.0.0 se ha desarrollado de acuerdo con el proceso de desarrollo y QA de wolfSSL (consulte https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance) y ha superado con éxito los criterios de calidad.
## Licencia
wolfCOSE es software libre licenciado bajo [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html); consulte [LICENSE](https://github.com/wolfssl/wolfcose/blob/main/LICENSE) para el texto completo.
Copyright (C) 2026 wolfSSL Inc.
## Soporte
Para licencias comerciales, contratos de soporte profesional o para analizar la incorporación de wolfCOSE en su entorno de producción, contacte con [wolfSSL](https://www.wolfssl.com/contact/).