COSE Library for PHP

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
• RFC 9864 - COSE: Fully-Specified 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)
• Fully-specified identifiers (RFC 9864): ESP256/384/512, ESB256/320/384/512, Ed25519, Ed448
• 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

Fully-Specified Algorithms (RFC 9864)

These identifiers determine the curve and the hash on their own, instead of leaving them to the other parameters of the key. They live in the Cose\Algorithm\Signature\FullySpecified namespace.

[!NOTE] Cose\Algorithm\Signature\FullySpecified\Ed25519 (-19) and Cose\Algorithm\Signature\EdDSA\Ed25519 (-8) compute the same signatures; only the algorithm identifier differs.

Ed448 is not covered by the sodium extension and goes through OpenSSL, which PHP only wires up for Edwards curves as of PHP 8.4. Call Ed448::isSupported() when the platform is not known in advance.

[!WARNING] RS1 (SHA-1) is not secure. It is kept only for the legacy authenticators that still rely on it. Creating it emits an E_USER_WARNING unless you explicitly acknowledge the risk:

use Cose\Algorithm\Signature\RSA\RS1;

$algorithm = RS1::create(acknowledgeInsecureAlgorithm: true);

As of the next major version, omitting that acknowledgement will throw an exception instead of warning.

MAC Algorithms

Validating RSA Keys

RFC 8812 defers to RFC 8230, section 6.1, which requires a modulus of 2048 bits or larger and expects implementations to handle up to 16K bits. The library never applies those bounds on its own; run them explicitly on a key before handing it to an algorithm:

use Cose\Key\RsaKey;
use Cose\Key\RsaKeyValidator;

$key = RsaKey::create($data);

// Throws an InvalidArgumentException when the key does not comply
RsaKeyValidator::create()->check($key);

// …or ask without the exception
if (! RsaKeyValidator::create()->isValid($key)) {
    // reject the key
}

// The bounds can be tightened
RsaKeyValidator::create(minimumModulusLength: 3072, maximumModulusLength: 8192)->check($key);

The validator also enforces the public exponent constraints of RFC 8017, section 3.1: an odd integer between 3 and n - 1.

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