README

CBOR Object Signing and Encryption (COSE) for PHP is a comprehensive library that provides full support for COSE operations including signing, encryption, and MAC (Message Authentication Code) operations.

This library implements:

• RFC 9052 - COSE: Structures and Process
• RFC 9053 - COSE: Initial Algorithms

Features

✅ Complete COSE Tag Support

• COSE_Sign1 (tag 18) - Single signature
• COSE_Sign (tag 98) - Multiple signatures
• COSE_Encrypt0 (tag 16) - Single recipient encryption
• COSE_Encrypt (tag 96) - Multiple recipients encryption
• COSE_Mac0 (tag 17) - MAC without recipients
• COSE_Mac (tag 97) - MAC with recipients

✅ Cryptographic Algorithms

• Signatures: ECDSA (ES256, ES384, ES512, ES256K), EdDSA (Ed25519, Ed448), RSA (RS256/384/512, PS256/384/512)
• MAC: HMAC with SHA-256/384/512
• Compatible with WebAuthn, FIDO2, and digital COVID certificates

✅ Modern PHP

• PHP 8.1+ with strict types
• Full type safety and PHPStan compliance
• Comprehensive test coverage

Installation

Install the library with Composer:

composer require web-auth/cose-lib

For COSE tag support (Sign, Encrypt, Mac operations), also install:

composer require spomky-labs/cbor-php

Quick Start

Verifying a COSE_Sign1 Signature

use CBOR\Decoder;
use CBOR\OtherObject\OtherObjectManager;
use CBOR\StringStream;
use CBOR\Tag\TagManager;
use Cose\Signature\CoseSign1Tag;
use Cose\Signature\Signature1;

// Setup decoder with COSE tag support
$tagManager = TagManager::create()->add(CoseSign1Tag::class);
$decoder = Decoder::create($tagManager, OtherObjectManager::create());

// Decode COSE_Sign1 message
$stream = new StringStream($encodedData);
$coseSign1 = $decoder->decode($stream);

// Extract components
$protectedHeader = $coseSign1->getProtectedHeader();
$payload = $coseSign1->getPayload();
$signature = $coseSign1->getSignature();

// Create signature structure for verification
$sigStructure = Signature1::create($protectedHeader, $payload);

// Verify (example with OpenSSL)
$isValid = openssl_verify(
    (string) $sigStructure,
    $derSignature,
    $publicKey,
    'sha256'
);

Creating a COSE_Sign1 Message

use CBOR\ByteStringObject;
use CBOR\MapItem;
use CBOR\MapObject;
use CBOR\NegativeIntegerObject;
use CBOR\UnsignedIntegerObject;
use Cose\Signature\CoseSign1Tag;

// Define headers
$protectedHeader = MapObject::create([
    MapItem::create(
        UnsignedIntegerObject::create(1), // alg
        NegativeIntegerObject::create(-7) // ES256
    ),
]);

$unprotectedHeader = MapObject::create([
    MapItem::create(
        UnsignedIntegerObject::create(4), // kid
        ByteStringObject::create('my-key-id')
    ),
]);

// Create COSE_Sign1
$coseSign1 = CoseSign1Tag::create(
    $protectedHeader,
    $unprotectedHeader,
    ByteStringObject::create('Message to sign'),
    ByteStringObject::create($signatureBytes)
);

// Encode to CBOR
$encoded = (string) $coseSign1;

Documentation

• Usage Guide - Complete documentation with examples
• RFC 9052 - COSE Structures
• RFC 9053 - COSE Algorithms

Use Cases

This library is perfect for:

• 🏥 Digital Health Certificates - COVID-19 vaccination passes (EU Digital COVID Certificate)
• 🔐 WebAuthn/FIDO2 - Authenticator attestation and assertion signatures
• 📱 IoT Security - Secure messaging for constrained devices
• 🌐 Web PKI - CBOR-based certificate chains
• 📄 Document Signing - Compact digital signatures

Supported Algorithms

Signature Algorithms

MAC Algorithms

Testing

Run the test suite with:

composer test

Or using Castor:

castor phpunit

The library includes comprehensive tests including:

• Unit tests for all COSE tag types
• Integration tests with real cryptographic operations
• COVID-19 certificate verification examples
• Test fixtures with actual certificates

Requirements

• PHP 8.1 or higher
• ext-json
• ext-openssl
• brick/math
• spomky-labs/pki-framework
• spomky-labs/cbor-php (for COSE tag support)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

For security vulnerabilities, please email security [at] spomky-labs.com instead of using the issue tracker.

Support

I bring solutions to your problems and answer your questions.

If you really love this project and the work I have done, or if you want me to prioritize your issues, you can support me:

• Become a sponsor on GitHub
• Become a Patreon

License

This software is released under the MIT License.

Credits

Maintained by Florent Morselli and contributors.

Made with ❤️ for the PHP community