Uma implementação rápida, portátil e leve de COSE + CBOR para sistemas embarcados. Suporta PQC, FIPS 140-3, DO-178 e MISRA C. Alimentado por wolfSSL.
# wolfCOSE
wolfCOSE é uma biblioteca C leve e rápida que implementa os padrões principais CBOR e COSE, com suporte de [wolfSSL](https://github.com/wolfSSL/wolfssl) para criptografia.
## Padrões e RFCs Suportados
* **Especificações Principais:**
* [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) - Algoritmos Totalmente Especificados para JOSE e COSE
* [RFC 9338](https://www.rfc-editor.org/rfc/rfc9338) - Contra-assinaturas COSE
* **Criptografia Pós-Quâ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
* **Atestação:**
* [RFC 9783](https://www.rfc-editor.org/rfc/rfc9783) - Perfil de Token de Atestação PSA do EAT
## Principais Recursos
* **Suíte COSE Completa (RFC 9052):** Suporte completo para todos os seis tipos de mensagem, incluindo `COSE_Sign1`, `COSE_Encrypt0` e `COSE_Mac0`.
* **Contra-assinaturas V2 (RFC 9338):** Contra-assinaturas in-place completas e abreviadas em todos os seis tipos de mensagem COSE marcados.
* **Criptografia Pós-Quântica:**
* ML-DSA (FIPS 204 / RFC 9964) em todos os níveis de segurança.
* Assinatura stateful baseada em hash HSS/LMS (RFC 8778 / CNSA 2.0).
* **Desempenho Rápido:** Em um Intel i9-11950H, o `COSE_Sign1` ponta a ponta atinge 66.538 assinaturas/s e 26.437 verificações/s com ES256, e 21.986 assinaturas/s e 53.686 verificações/s com ML-DSA-44. Consulte os [detalhes de desempenho e footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html) e [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/).
* **Atestação PSA:** Emissão e verificação de EAT / PSA Token com suporte a assinatura delegada por HSM.
* **41 Algoritmos Criptográficos:** Ampla cobertura de algoritmos em assinatura, criptografia, MAC e distribuição de chaves.
* **Design Embedded-First:** Zero alocação dinâmica de memória (sem heap, zero `.data`/`.bss`). Opera em buffers fornecidos pelo chamador com uso de pilha limitado.
* **Caminho FIPS 140-3:** Usa wolfCrypt (Certificado FIPS #4718) como sua única dependência criptográfica.
* **Integrado ao STM32:** Pacote STM32Cube drop-in (`I-CUBE-wolfCOSE`) disponível para STM32CubeMX / IDE ([Detalhes](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html)).
## Algoritmos Suportados
* **Assinaturas Digitais:**
* **Clássicos:** `ESP256`, `ESP384`, `ESP512`, `Ed25519`, `Ed448`, `PS256`, `PS384`, `PS512`
* **Pós-Quânticos:** `ML-DSA-44`, `ML-DSA-65`, `ML-DSA-87`
* **Stateful Baseados em Hash:** `HSS-LMS`
* **Criptografia (AEAD):**
* `AES-GCM` (128 / 192 / 256)
* `AES-CCM` (variantes)
* `ChaCha20-Poly1305`
* **Autenticação de Mensagem (MAC):**
* `HMAC-SHA256`, `HMAC-SHA384`, `HMAC-SHA512`
* `AES-MAC`
* **Distribuição de Chaves:**
* `Direct`
* `AES Key Wrap`
* `ECDH-ES + HKDF`
## Tipos de Mensagem COSE (RFC 9052)
wolfCOSE implementou todas as mensagens da RFC 9052, tanto nas variantes de ator único quanto multi-ator:
| Mensagem | RFC 9052 | API | Propósito |
|---|---|---|---|
| `COSE_Sign1` | Sec. 4.2 | `wc_CoseSign1_Sign` / `wc_CoseSign1_Verify` | Assinatura de signatário único |
| `COSE_Sign` | Sec. 4.1 | `wc_CoseSign_Sign` / `wc_CoseSign_Verify` | **Multi-signatário** (assinaturas independentes sobre o mesmo payload) |
| `COSE_Encrypt0` | Sec. 5.2 | `wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt` | AEAD de destinatário único |
| `COSE_Encrypt` | Sec. 5.1 | `wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt` | **Multi-destinatário** (um ciphertext, muitos destinatários via Direct / AES-KW / ECDH-ES) |
| `COSE_Mac0` | Sec. 6.2 | `wc_CoseMac0_Create` / `wc_CoseMac0_Verify` | MAC de destinatário único |
| `COSE_Mac` | Sec. 6.1 | `wc_CoseMac_Create` / `wc_CoseMac_Verify` | MAC **multi-destinatário** (chave MAC compartilhada, distribuída aos destinatários) |
| `COSE_Key` / `COSE_KeySet` | Sec. 7 | `wc_CoseKey_Encode` / `wc_CoseKey_Decode` | Serialização de chaves para todos os tipos de chave |
Contra-assinaturas da RFC 9338 podem ser anexadas a qualquer mensagem marcada nesta
tabela. Use `wc_Cose_AddCounterSignature()` ou
`wc_Cose_AddCounterSignature0()` para adicionar uma, e depois verifique-a independentemente com
a API correspondente `wc_Cose_VerifyCounterSignature*()`.
## Dependências (wolfSSL)
wolfCOSE requer [wolfSSL](https://www.wolfssl.com/) como seu backend criptográfico.
**Versão mínima suportada: v5.8.0-stable**. Alguns algoritmos opcionais requerem
versões mais recentes; consulte [Getting Started](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html#prerequisites) para
pisos de dependência específicos de recursos e instruções de build. HSS/LMS (RFC 8778)
requer v5.9.2-stable ou posterior.
Escolha uma configuração de build com base nos algoritmos que você precisa.
### Build Mínimo (ECC + AES-GCM)
Isso fornece COSE Sign1 (ESP256/384/512) e 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 um footprint menor do wolfCrypt, adicione `--enable-cryptonly` para remover a pilha
TLS e desabilitar os algoritmos que um build 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) e [Tuning for Speed](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)
para reduzir ainda mais o wolfCOSE e o wolfCrypt em MCUs.
### Build Mínimo (Somente Pós-Quântico / ML-DSA)
Para assinatura puramente pós-quântica com 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 são incluídos automaticamente por `--enable-mldsa`. A
API `wc_MlDsaKey` requer wolfSSL mais recente que v5.9.1-stable.)
### Build Completo (Todos os 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
```
## Build
```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
```
### Alvos de Build
| Alvo | Descrição |
|--------|-------------|
| `make all` | Compila `libwolfcose.a` (somente biblioteca principal) |
| `make shared` | Compila `libwolfcose.so` |
| `make test` | Compila + executa testes unitários CBOR e COSE |
| `make pkg-config-test` | Verifica a descoberta de pacotes wolfSSL e sobrescritas |
| `make eat-psa-test` | Compila + executa a suíte de conformidade explícita completa RFC 9783 PSA/EAT |
| `make eat-psa-min-buffers-test` | Executa a suíte completa PSA/EAT com limites de alvo restrito `WOLFCOSE_MIN_BUFFERS` |
| `make eat-psa-config-check` | Verifica que PSA/EAT está ausente por padrão e valida combinações de feature-gate |
| `make psa-eat-lean-verify` | Compila + executa o exemplo completo de vetor RFC verify-only `#tfm` PSA/EAT |
| `make psa-eat-demo` | Emite, verifica e avalia um token de onboarding de dispositivo RFC 9783 atual |
| `make tool` | Compila a ferramenta CLI (`tools/wolfcose_tool`) |
| `make tool-test` | Autoteste round-trip para todos os 17 algoritmos |
| `make demo` | Compila + executa demo de ciclo de vida (11 algoritmos) |
| `make clean` | Remove todos os artefatos de build |
## Início Rápido
### Exemplos
Consulte `examples/` para código funcional completo:
- `sign1_demo.c`, `encrypt0_demo.c`, `mac0_demo.c`: demos de algoritmos
- `lifecycle_demo.c`: fluxo de trabalho completo edge-to-cloud
- `comprehensive/`: testes de matriz de algoritmos
- `scenarios/`: assinatura de firmware, atestação, configuração de frota
- `psa_eat_demo.c`: onboarding de dispositivo RFC 9783 com avaliação de medição
- `psa_eat_verify_lean.c`: verificação Sign1 do perfil atual RFC 9783 em um build enxuto
## CI / Testes
Executado em cada push e PR:
- **Build + Test**: Ubuntu, macOS, GCC 10-14, Clang 14-18
- **Testes Abrangentes**: ~240 testes de combinação de algoritmos
- **Análise Estática**: cppcheck, Clang analyzer, GCC `-fanalyzer`
- **MISRA C 2012**: cppcheck `--addon=misra` verificando todos os caminhos de código do wolfCOSE
- **MISRA C 2023**: avisos estritos do GCC e clang-tidy (`bugprone-*`, `cert-*`, `clang-analyzer-*`, `misc-*`)
- **Coverity Scan**: análise noturna de defeitos
- **Análise Estática Interna:** Ferramentas avançadas de análise estática Fenrir wolfssl
- **Cobertura de Código**: 100% de cobertura de linhas exigida para cada arquivo fonte do 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>
## Documentação
O manual oficial do wolfCOSE é publicado em
[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): Instruções de build e primeiros passos
- [Message Types](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html): Todas as seis mensagens RFC 9052 (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) e contra-assinaturas RFC 9338 com exemplos de código
- [Algorithms](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html): Lista completa dos 41 algoritmos suportados com IDs COSE
- [API Reference](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html): Assinaturas de funções, estruturas de dados, códigos de erro
- [Macros](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html): Configuração em tempo de compilação, ajuste de tamanho e política de nonce ECDSA
- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html): Perfis de token PSA RFC 9783, APIs, macros e orientações de segurança
- [Footprint](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html): Números de tamanho e velocidade, desktop e em dispositivo
- [Testing](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html): Infraestrutura de testes, cobertura e injeção de falhas
- [MISRA Compliance](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html): Status de conformidade MISRA C:2012 e C:2023 e justificativa de desvios
- [Project Structure](https://www.wolfssl.com/documentation/manuals/wolfcose/Project-Structure.html): Layout dos arquivos fonte
- [STM32Cube](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html): Instale e execute o wolfCOSE como um pacote STM32Cube no dispositivo
As fontes do manual ficam em [`docs/`](https://github.com/wolfssl/wolfcose/blob/main/docs); `mkdocs.yml` define a navegação
e o ferramental compartilhado [`wolfSSL/documentation`](https://github.com/wolfSSL/documentation)
compila o HTML e o PDF. Consulte [docs/dev/DOCS-BUILD.md](https://github.com/wolfssl/wolfcose/blob/main/docs/dev/DOCS-BUILD.md)
para visualizações locais e como as alterações chegam ao site.
## Notas de Versão
A versão atual é **2.0.0**. Ela adiciona assinaturas HSS/LMS padronizadas (RFC 8778), contra-assinaturas COSE (RFC 9338), atestação PSA/EAT (RFC 9783), IDs de assinatura RFC 9864, assinatura delegada, APIs expandidas de chave e CBOR, COSE-HPKE experimental e amplo hardening, tudo com zero alocação dinâmica. Consulte [ChangeLog.md](https://github.com/wolfssl/wolfcose/blob/main/ChangeLog.md) para as notas de versão completas.
wolfCOSE 2.0.0 foi desenvolvido de acordo com o processo de desenvolvimento e QA da wolfSSL (consulte https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance) e passou com sucesso nos critérios de qualidade.
## Licença
wolfCOSE é software livre licenciado sob [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html); consulte [LICENSE](https://github.com/wolfssl/wolfcose/blob/main/LICENSE) para o texto completo.
Copyright (C) 2026 wolfSSL Inc.
## Suporte
Para licenciamento comercial, contratos de suporte profissional ou para discutir a adoção do wolfCOSE em seu ambiente de produção, entre em contato com a [wolfSSL](https://www.wolfssl.com/contact/).