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