wolfCOSE

wolfCOSE è una libreria C leggera che implementa CBOR (RFC 8949), COSE (RFC 9052/9053) e ML-DSA per COSE (RFC 9964) post-quantistico, utilizzando wolfSSL come backend crittografico.

Funzionalità Principali

Set completo di messaggi RFC 9052: tutti e sei i tipi di messaggio COSE, inclusi multi-firmatario COSE_Sign e multi-destinatario COSE_Encrypt / COSE_Mac
Firma post-quantistica: ML-DSA (FIPS 204) a tutti e tre i livelli di sicurezza, con COSE_Key RFC 9964 (tipo di chiave AKP, chiavi private basate su seed)
40 algoritmi tra firma, cifratura, MAC e distribuzione delle chiavi
Zero allocazione dinamica: senza allocazioni heap e non ricorsivo. Ogni operazione viene eseguita su buffer forniti dal chiamante entro un limite di stack circoscritto e personalizzabile per target (nulla sullo heap, zero .data/.bss)
Ingombro ridotto: wolfCOSE ES256 COSE_Sign1 (motore COSE + CBOR) ~5.1 KB solo verifica e ~6.8 KB firma + verifica. La flash totale inclusa wolfCrypt è ~26.2 KB solo verifica (WOLFCOSE_LEAN_VERIFY) e ~34.6 KB firma + verifica
Veloce: (ES256 COSE_Sign1, x86_64, wolfCrypt sp_256 asm): 66,538 firme/s, 26,437 verifiche/s
Post-quantistico allo stesso costo: per ML-DSA-44 COSE_Sign1 la flash totale inclusa wolfCrypt è ~20.8 KB solo verifica (WOLFCOSE_LEAN_VERIFY_MLDSA) e ~35.8 KB firma + verifica, entro circa 1 KB dall'ES256 classico. La sola parte wolfCOSE è rispettivamente 4.6 KB e ~6.6 KB. Vedi Footprint
Percorso verso FIPS 140-3: tramite wolfCrypt Certificato FIPS #4718 (unica dipendenza crittografica)

Algoritmi Supportati

Firma: ES256, ES384, ES512, EdDSA (Ed25519/Ed448), PS256/384/512, ML-DSA-44/65/87

Cifratura: AES-GCM (128/192/256), ChaCha20-Poly1305, varianti AES-CCM

MAC: HMAC-SHA256/384/512, AES-MAC

Distribuzione delle Chiavi: Direct, AES Key Wrap, ECDH-ES+HKDF

Tipi di Messaggio COSE (RFC 9052)

wolfCOSE ha implementato tutti i messaggi RFC 9052, sia nelle varianti single-actor che multi-actor:

Messaggio	RFC 9052	API	Scopo
`COSE_Sign1`	Sec. 4.2	`wc_CoseSign1_Sign` / `wc_CoseSign1_Verify`	Firma con singolo firmatario
`COSE_Sign`	Sec. 4.1	`wc_CoseSign_Sign` / `wc_CoseSign_Verify`	Multi-firmatario (firme indipendenti sullo stesso payload)
`COSE_Encrypt0`	Sec. 5.2	`wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt`	AEAD con singolo destinatario
`COSE_Encrypt`	Sec. 5.1	`wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt`	Multi-destinatario (un solo testo cifrato, molti destinatari tramite Direct / AES-KW / ECDH-ES)
`COSE_Mac0`	Sec. 6.2	`wc_CoseMac0_Create` / `wc_CoseMac0_Verify`	MAC con singolo destinatario
`COSE_Mac`	Sec. 6.1	`wc_CoseMac_Create` / `wc_CoseMac_Verify`	MAC multi-destinatario (chiave MAC condivisa, distribuita ai destinatari)
`COSE_Key` / `COSE_KeySet`	Sec. 7	`wc_CoseKey_Encode` / `wc_CoseKey_Decode`	Serializzazione delle chiavi per tutti i tipi di chiave

Prerequisiti (wolfSSL)

wolfCOSE richiede wolfSSL come backend crittografico. Versione minima supportata: v5.8.0-stable (la prima release con il simbolo pubblico wc_ForceZero). La firma post-quantistica utilizza l'API canonica FIPS 204 wc_MlDsaKey, che arriva in wolfSSL dopo v5.9.1-stable; compilare wolfCOSE con v5.8.0–v5.9.1 funziona per tutto tranne ML-DSA. Le release precedenti della serie 5.x possono essere tecnicamente supportate ma richiedono modifiche a livello di sorgente; contatta wolfSSL per il supporto commerciale.

Scegli una configurazione di build in base agli algoritmi di cui hai bisogno.

Build Minima (ECC + AES-GCM)

Con questa ottieni COSE Sign1 (ES256/384/512) e Encrypt0 (AES-GCM):

cd wolfssl
./autogen.sh
./configure --enable-ecc --enable-aesgcm \
            --enable-sha384 --enable-sha512 --enable-keygen
make && sudo make install
sudo ldconfig

Algoritmi abilitati: ES256, ES384, ES512, AES-GCM-128/192/256

Per un ingombro wolfCrypt ridotto, aggiungi --enable-cryptonly per eliminare lo stack TLS e disabilitare gli algoritmi che una build Sign1 + Encrypt0 non usa mai:

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

Vedi Tuning for Size e Tuning for Speed per ridurre ulteriormente l'ingombro di wolfCOSE e wolfCrypt su MCU.

Build Minima (Solo Post-Quantum / ML-DSA)

Per la firma puramente post-quantistica con ML-DSA-44/65/87:

cd wolfssl
./autogen.sh
./configure --enable-cryptonly --enable-mldsa
make && sudo make install
sudo ldconfig

Algoritmi abilitati: ML-DSA-44, ML-DSA-65, ML-DSA-87 (SHAKE-128/256 vengono inclusi automaticamente da --enable-mldsa. L'API wc_MlDsaKey richiede una versione di wolfSSL successiva alla v5.9.1-stable.)

Build Completa (Tutti gli Algoritmi)

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-hkdf --enable-aeskeywrap
make && sudo make install
sudo ldconfig

Build

# 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

Target di Build

Target	Descrizione
`make all`	Compila `libwolfcose.a` (solo libreria principale)
`make shared`	Compila `libwolfcose.so`
`make test`	Compila + esegue i test unitari CBOR e COSE
`make tool`	Compila lo strumento CLI (`tools/wolfcose_tool`)
`make tool-test`	Self-test round-trip per tutti i 17 algoritmi
`make demo`	Compila + esegue la demo del ciclo di vita (11 algoritmi)
`make clean`	Rimuove tutti gli artefatti di build

Avvio Rapido

Esempi

Vedi examples/ per esempi di codice funzionante e completo:

sign1_demo.c, encrypt0_demo.c, mac0_demo.c: demo degli algoritmi
lifecycle_demo.c: flusso di lavoro completo edge-to-cloud
comprehensive/: test della matrice degli algoritmi
scenarios/: firma del firmware, attestazione, configurazione della flotta

CI / Test

Viene eseguito a ogni push e PR:

Build + Test: Ubuntu, macOS, GCC 10-14, Clang 14-18
Test Completi: ~240 test di combinazioni di algoritmi
Analisi Statica: cppcheck, Clang analyzer, GCC -fanalyzer
MISRA C 2012: cppcheck --addon=misra che verifica tutti i percorsi del codice wolfCOSE
MISRA C 2023: warning GCC rigorosi e clang-tidy (bugprone-*, cert-*, clang-analyzer-*, misc-*)
Coverity Scan: analisi notturna dei difetti
Analisi Statica Interna Avanzata: strumenti di analisi statica avanzata Fenrir di wolfSSL
Copertura del Codice: 99.3% per wolfcose.c, 100% per wolfcose_cbor.c

make coverage                  # Run tests with gcov
make coverage-force-failure    # Include crypto failure path testing

Documentazione

La documentazione completa è disponibile nella Wiki:

Getting Started: istruzioni di build e primi passi
Message Types: tutti e sei i messaggi RFC 9052 (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) con esempi di codice
Algorithms: elenco completo dei 40 algoritmi supportati con ID COSE
API Reference: firme delle funzioni, strutture dati, codici di errore
Macros: opzioni di configurazione in fase di compilazione
Footprint: dati su dimensioni e velocità, su desktop e su dispositivo
Testing: infrastruttura di test, copertura e injection di guasti
MISRA Compliance: stato di conformità MISRA C:2012 e C:2023 e motivazione delle deviazioni
Project Structure: organizzazione dei file sorgente

Note di Rilascio

La release corrente è la 1.0.0, la prima release stabile: il set completo di messaggi COSE RFC 9052 (tutti e sei i tipi di messaggio, single- e multi-actor), 40 algoritmi e ML-DSA post-quantistico standardizzato (RFC 9964), il tutto con zero allocazione dinamica. Vedi ChangeLog.md per le note di rilascio complete.

wolfCOSE 1.0.0 è stato sviluppato secondo il processo di sviluppo e QA di wolfSSL (vedi https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance) e ha superato con successo i criteri di qualità.

Licenza

wolfCOSE è un software libero concesso in licenza GPLv3; vedi LICENSE per il testo completo.

Supporto

Per licenze commerciali, contratti di supporto professionale o per discutere come integrare wolfCOSE nel tuo ambiente di produzione, contatta wolfSSL.

wolfCOSE v2.0.0

Categorie