wolfCOSE

wolfCOSE é uma biblioteca C leve que implementa CBOR (RFC 8949), COSE (RFC 9052/9053) e o ML-DSA pós-quântico para COSE (RFC 9964), usando wolfSSL como backend criptográfico.

Principais Recursos

• Conjunto completo de mensagens RFC 9052: todos os seis tipos de mensagem COSE, incluindo COSE_Sign com múltiplos assinantes e COSE_Encrypt / COSE_Mac com múltiplos destinatários
• Assinatura pós-quântica: ML-DSA (FIPS 204) nos três níveis de segurança, com COSE_Key RFC 9964 (tipo de chave AKP, chaves privadas baseadas em semente)
• 40 algoritmos em assinatura, criptografia, MAC e distribuição de chaves
• Zero alocação dinâmica: sem alocação de heap e não recursivo. Toda operação é executada em buffers fornecidos pelo chamador dentro de um teto de pilha limitado e personalizável por alvo (nada no heap, zero .data/.bss)
• Pegada mínima: ES256 COSE_Sign1 wolfCOSE (motor COSE + CBOR) ~5,1 KB somente verificação e ~6,8 KB assinatura + verificação. O flash total, incluindo wolfCrypt, é ~26,2 KB somente verificação (WOLFCOSE_LEAN_VERIFY) e ~34,6 KB assinatura + verificação
• Rápido: (ES256 COSE_Sign1, x86_64, wolfCrypt sp_256 asm): 66.538 assinaturas/s, 26.437 verificações/s
• Pós-quântico pelo mesmo custo: o flash total de ML-DSA-44 COSE_Sign1, incluindo wolfCrypt, é ~20,8 KB somente verificação (WOLFCOSE_LEAN_VERIFY_MLDSA) e ~35,8 KB assinatura + verificação, dentro de cerca de 1 KB do ES256 clássico. A parte wolfCOSE sozinha é 4,6 KB e ~6,6 KB, respectivamente. Consulte Footprint
• Caminho para FIPS 140-3: via wolfCrypt Certificado FIPS nº 4718 (única dependência criptográfica)

Algoritmos Suportados

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

Criptografia: AES-GCM (128/192/256), ChaCha20-Poly1305, AES-CCM variants

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

Distribuição de Chaves: Direct, AES Key Wrap, ECDH-ES+HKDF

Tipos de Mensagem COSE (RFC 9052)

wolfCOSE implementou todas as mensagens RFC 9052, tanto nas variantes de ator único quanto nas de múltiplos atores:

Pré-requisitos (wolfSSL)

wolfCOSE requer wolfSSL como backend criptográfico. Versão mínima suportada: v5.8.0-stable (primeira versão com o símbolo público wc_ForceZero). A assinatura pós-quântica usa a API canônica wc_MlDsaKey do FIPS 204, que chega ao wolfSSL após v5.9.1-stable; compilar wolfCOSE com v5.8.0–v5.9.1 funciona para tudo, exceto ML-DSA. Versões 5.x mais antigas podem ser suportadas tecnicamente, mas exigem alterações no nível do código-fonte; entre em contato com a wolfSSL para suporte comercial.

Escolha uma configuração de compilação com base nos algoritmos de que você precisa.

Compilação Mínima (ECC + AES-GCM)

Isso fornece 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

Algoritmos habilitados: ES256, ES384, ES512, AES-GCM-128/192/256

Para uma pegada wolfCrypt menor, adicione --enable-cryptonly para eliminar a pilha TLS e desabilitar os algoritmos que uma compilação Sign1 + Encrypt0 nunca usa:

./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 Ajuste para Tamanho e Ajuste para Velocidade para otimizar ainda mais wolfCOSE e wolfCrypt em MCUs.

Compilação Mínima (Somente Pós-Quântico / ML-DSA)

Para assinatura pós-quântica pura com ML-DSA-44/65/87:

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

Compilação Completa (Todos os Algoritmos)

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

Compilação

# 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 Compilação

Início Rápido

Exemplos

Consulte examples/ para obter código funcional completo:

• sign1_demo.c, encrypt0_demo.c, mac0_demo.c: demonstrações 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

CI / Testes

Executado a cada push e PR:

• Build + Teste: Ubuntu, macOS, GCC 10-14, Clang 14-18
• Testes Abrangentes: ~240 testes de combinação de algoritmos
• Análise Estática: cppcheck, analisador Clang, 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 Avançada: ferramentas avançadas de análise estática Fenrir wolfssl
• Cobertura de Código: 99,3% para wolfcose.c, 100% para wolfcose_cbor.c

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

Documentação

A documentação completa está disponível na Wiki:

• Primeiros Passos: instruções de compilação e primeiros passos
• Tipos de Mensagem: todas as seis mensagens RFC 9052 (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) com exemplos de código
• Algoritmos: lista completa dos 40 algoritmos suportados com IDs COSE
• Referência da API: assinaturas de funções, estruturas de dados, códigos de erro
• Macros: opções de configuração em tempo de compilação
• Footprint: números de tamanho e velocidade, em desktop e no dispositivo
• Testes: infraestrutura de testes, cobertura e injeção de falhas
• Conformidade MISRA: status de conformidade com MISRA C:2012 e C:2023 e justificativa de desvios
• Estrutura do Projeto: organização dos arquivos-fonte

Notas de Versão

O lançamento atual é o 1.0.0, o primeiro lançamento estável: o conjunto completo de mensagens COSE RFC 9052 (todos os seis tipos de mensagem, de ator único e múltiplos atores), 40 algoritmos e ML-DSA pós-quântico padronizado (RFC 9964), tudo com zero alocação dinâmica. Consulte ChangeLog.md para as notas de versão completas.

O wolfCOSE 1.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 é um software livre licenciado sob GPLv3; consulte 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.