Loheide-eu-mitarbeiterplatt.../vendor/web-auth/cose-lib
Friederich Loheide 9c0f8de791
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 1m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 1m12s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 1m7s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 1m19s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 1m32s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 1m22s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 1m32s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 1m35s
CI / Build-Artefakte aktuell (pull_request) Failing after 1m7s
Phase 0: Fundament für Inhaus
- Laravel 13 mit Filament 5 (Admin), Inertia 3 + Vue 3 + Vuetify 4 (Material 3)
- Anmeldung über Fortify (Login, Passwort vergessen/ändern), keine Selbstregistrierung
- Profil mit Profilbild (WebP in festen Größen), Personenseiten, Header mit Avatar-Menü
- Material-3-Farbschema aus der Primärfarbe, hell/dunkel/System pro Person
- Basis-Branding (Portalname, Logo, Primärfarbe) im Admin unter „Erscheinungsbild“
- Benutzerverwaltung im Admin, Zugang vorläufig über is_admin
- vendor/ (ohne Dev-Pakete) und Frontend-Build mitversioniert, Dev-Pakete in vendor-dev/
- PHPUnit-Tests gegen MySQL/MariaDB, Forgejo-CI-Matrix, Docker-Entwicklungsumgebung
- VERSION, CHANGELOG.md und CONTRIBUTING.md mit Release-Ablauf

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 20:35:30 +00:00
..
src Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
CODE_OF_CONDUCT.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
composer.json Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
LICENSE Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
README.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
RELEASES.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
SECURITY.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00

COSE Library for PHP

CI Latest Stable Version Total Downloads License

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

✅ RFC 9052 Cryptographic Structures

  • Sig_structure: Signature1 (§4.4) and Signature, which also covers the signer's own protected header
  • MAC_structure: Mac0Structure and MacStructure (§6.3) — a MAC tag covers this, never the bare payload
  • Enc_structure: Encrypt0Structure, EncryptStructure and RecipientStructure (§5.3)
  • Each takes the optional external_aad, defaulting to the zero-length byte string the RFC prescribes

✅ RFC 9052 Header and Structure Rules

  • CoseHeaders reads the two buckets of any COSE message: a label is an integer or a text string (§1.5) and the two never answer for each other, the zero-length protected header is accepted (§3), trailing bytes in the protected bucket are not, and the protected value wins a combined lookup
  • CoseSignature and CoseRecipient are the checked views over the signatures and recipients lists ([+ ...])
  • Works on the COSE message classes of spomky-labs/cbor-php 3.4.0

✅ COSE Tag Support (via spomky-labs/cbor-php 3.4.0)

  • CBOR\Tag\CoseSign1Tag (18), CoseSignTag (98), CoseEncrypt0Tag (16), CoseEncryptTag (96), CoseMac0Tag (17), CoseMacTag (97), plus CwtTag (61), all registered in the default decoder
  • The Cose\...Tag classes of this library are deprecated since 4.8.0 and removed in 5.0.0; see Upgrading

✅ 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

✅ Key Restrictions (RFC 9052 §7.1)

  • Opt-in enforcement of the alg (label 3) and key_ops (label 4) parameters a COSE key carries
  • Turned on per algorithm or for a whole Manager: ES256::create()->withKeyRestrictionsEnforced()
  • See Key Restrictions

✅ 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:^3.3.4"

3.4.0 is the floor this library declares (conflict: <3.4.0). Two things come from there rather than from here: the CBOR decoder enforces the header-map rules of RFC 9052 — a label appearing twice in a map makes the message malformed (§3, §9), and nesting is bounded so that a crafted header cannot exhaust the memory of the process — and, since 3.4.0, the six COSE message classes themselves.

Quick Start

Verifying a COSE_Sign1 Signature

use CBOR\Decoder;
use CBOR\ListObject;
use CBOR\OtherObject\NullObject;
use CBOR\StringStream;
use CBOR\Tag\CoseSign1Tag;
use Cose\Algorithm\Signature\ECDSA\ES256;
use Cose\Key\Ec2Key;
use Cose\Signature\Signature1;
use Cose\Structure\CoseHeaders;

// The key of the signer you trust, and the algorithm you expect it to be used with.
$key = Ec2Key::create($theCoseKeyYouPinned);
$algorithm = ES256::create();
// The protected header labels this application knows how to process (1 = alg, 2 = crit).
$understoodLabels = [1, 2];

// cbor-php 3.4.0 registers the six COSE tags in the default decoder: tag 18 resolves on its own.
$coseSign1 = Decoder::create()->decode(new StringStream($encodedData));
if (! $coseSign1 instanceof CoseSign1Tag) {
    throw new RuntimeException('Not a COSE_Sign1 message');
}

// cbor-php carries the header buckets; this library reads them the way RFC 9052 defines them.
$headers = CoseHeaders::fromMessage($coseSign1);

// RFC 9052 §3.1: bind the signature to the algorithm the protected header declares.
// The label is matched by type as well as by value, so the text string "1" — a different label under §1.5 —
// never answers a lookup for the integer label 1.
$alg = $headers->getProtectedHeaderParameter(1);
if ($alg === null || (int) $alg->normalize() !== $algorithm::identifier()) {
    throw new RuntimeException('Unexpected or missing "alg" in the protected header');
}

// RFC 9052 §3.1: every parameter listed in "crit" must be processed, or the message must be rejected.
$crit = $headers->getProtectedHeaderParameter(2);
if ($crit !== null) {
    if (! $crit instanceof ListObject) {
        throw new RuntimeException('"crit" is not an array');
    }
    foreach ($crit as $label) {
        if (! in_array((int) $label->normalize(), $understoodLabels, true)) {
            throw new RuntimeException('Unsupported critical header parameter');
        }
    }
}

// RFC 9052 §4.2: a nil payload is detached and the application supplies the content itself.
$payload = $coseSign1->getPayload();
if ($payload instanceof NullObject) {
    throw new RuntimeException('The payload is detached; supply it from the application');
}

// Verify the Sig_structure the signature covers
$sigStructure = Signature1::create($coseSign1->getProtectedHeader(), $payload);
$isValid = $algorithm->verify((string) $sigStructure, $key, $coseSign1->getSignature()->getValue());

Important

The library verifies signatures; it does not decide what a message is allowed to say. Checking that alg is the one expected for that key, and refusing any crit label the application does not process, are the caller's responsibility (RFC 9052 §3.1) — the snippet above is the shape they take. tests/Signature/DocumentedVerifierTest.php runs exactly this code.

Creating a COSE_Sign1 Message

use CBOR\ByteStringObject;
use CBOR\ListObject;
use CBOR\MapItem;
use CBOR\MapObject;
use CBOR\NegativeIntegerObject;
use CBOR\Tag\CoseSign1Tag;
use CBOR\UnsignedIntegerObject;
use Cose\Algorithm\Signature\ECDSA\ES256;
use Cose\Key\Ec2Key;
use Cose\Signature\Signature1;
use Cose\Structure\HeaderMapHelper;

$algorithm = ES256::create();
$key = Ec2Key::create($yourPrivateCoseKey);

// Define headers
$protectedHeader = MapObject::create([
    MapItem::create(
        UnsignedIntegerObject::create(1),                  // alg
        NegativeIntegerObject::create(ES256::identifier()) // ES256 (-7)
    ),
]);
$unprotectedHeader = MapObject::create([
    MapItem::create(
        UnsignedIntegerObject::create(4),                  // kid
        ByteStringObject::create('my-key-id')
    ),
]);
$payload = ByteStringObject::create('Message to sign');

// The signature covers the Sig_structure, never the payload on its own. Encode the protected bucket once, so the
// bytes that are signed are the bytes the message carries. HeaderMapHelper applies RFC 9052 §3 on the way out: an
// empty map becomes h'' rather than h'a0', and the labels are checked (§1.5, §9).
$protectedHeaderAsBytes = HeaderMapHelper::encodeProtected($protectedHeader);
$toBeSigned = Signature1::create($protectedHeaderAsBytes, $payload);
$signature = ByteStringObject::create($algorithm->sign((string) $toBeSigned, $key));

// Assemble the message around those exact bytes
$coseSign1 = CoseSign1Tag::create(ListObject::create([
    $protectedHeaderAsBytes,
    $unprotectedHeader,
    $payload,
    $signature,
]));

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

Note

CoseSign1Tag::createFromComponents($protectedHeader, $unprotectedHeader, $payload, $signature) takes the protected header as a map and encodes it itself, which is shorter but re-encodes what you already signed. Use it when the signature is computed after the message, and create() — as above — when the bytes have to travel verbatim. examples/01-sign1.php is the whole round trip, key generation included, and runs as it stands.

Documentation

  • Examples - A runnable program per topic; php examples/01-sign1.php to start
  • 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

Algorithm Identifier Description
ES256 -7 ECDSA with SHA-256
ES384 -35 ECDSA with SHA-384
ES512 -36 ECDSA with SHA-512
ES256K -47 ECDSA with secp256k1
EdDSA -8 EdDSA
Ed25519 -8 Alias of EdDSA (Curve25519); see -19 below for the fully-specified form
Ed256 -260 Ed25519 over a SHA-256 digest — non-standard, see below
Ed512 -261 Ed25519 over a SHA-512 digest — non-standard, see below
RS256 -257 RSASSA-PKCS1-v1_5 with SHA-256
RS384 -258 RSASSA-PKCS1-v1_5 with SHA-384
RS512 -259 RSASSA-PKCS1-v1_5 with SHA-512
PS256 -37 RSASSA-PSS with SHA-256
PS384 -38 RSASSA-PSS with SHA-384
PS512 -39 RSASSA-PSS with SHA-512
RS1 -65535 RSASSA-PKCS1-v1_5 with SHA-1 — legacy only, see below

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.

Algorithm Identifier Description
ESP256 -9 ECDSA with the P-256 curve and SHA-256
ESP384 -51 ECDSA with the P-384 curve and SHA-384
ESP512 -52 ECDSA with the P-521 curve and SHA-512
ESB256 -265 ECDSA with the brainpoolP256r1 curve and SHA-256
ESB320 -266 ECDSA with the brainpoolP320r1 curve and SHA-384
ESB384 -267 ECDSA with the brainpoolP384r1 curve and SHA-384
ESB512 -268 ECDSA with the brainpoolP512r1 curve and SHA-512
Ed25519 -19 EdDSA with the Ed25519 parameter set
Ed448 -53 EdDSA with the Ed448 parameter set — requires PHP 8.4 or later

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

Ed256 (-260) and Ed512 (-261) are not defined by any specification, and their identifiers are not theirs. Both hash the message and sign the digest with pure Ed25519, without the dom2 prefix that would make it the Ed25519ph of RFC 8032 §5.1 — whose §8.5 says prehashed variants "SHOULD NOT be used" anyway. IANA has since assigned -260 to WalnutDSA (RFC 9021) and -261 to TurboSHAKE128 (RFC 9861), so a conforming implementation reads objects produced by these classes as those algorithms. Despite its name, Ed512 is not Ed448 and rejects an Ed448 key; EdDSA with Curve448 is Cose\Algorithm\Signature\FullySpecified\Ed448 (-53).

No authenticator emits these identifiers. Prefer Ed25519 (-8 or -19). They are kept for the deployments that already use the construction on both ends, and only against an explicit acknowledgement:

use Cose\Algorithm\Signature\EdDSA\Ed256;

$algorithm = Ed256::create(acknowledgeNonStandardAlgorithm: true);

As of the next major version, omitting that acknowledgement will throw an exception, and the identifiers will move out of the range IANA administers.

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

The same acknowledgement applies to Algorithms::getOpensslAlgorithmFor() and Algorithms::getHashAlgorithmFor(), which hand out the very same primitive without any object being created:

use Cose\Algorithms;

$digest = Algorithms::getOpensslAlgorithmFor(Algorithms::COSE_ALGORITHM_RS1, acknowledgeInsecureAlgorithm: true);

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

MAC Algorithms

Algorithm Identifier Description
HS256 5 HMAC with SHA-256
HS384 6 HMAC with SHA-384
HS512 7 HMAC with SHA-512
HS256/64 4 HMAC with SHA-256 truncated to 64 bits

The HMAC Key

RFC 9053, section 3.1 requires implementations "creating and validating MAC values" to validate the key type, the key length and the algorithm. The key value k is a bstr (section 7.3), so hash() and verify() reject — with an InvalidArgumentException — a key that is not symmetric, or whose k is missing, is not a PHP string, or is empty. A decoded CBOR object has to be normalized to its value first: a CBOR\ByteStringObject is not a byte string.

A key shorter than the output of the underlying hash function (32 bytes for HS256 and HS256/64, 48 for HS384, 64 for HS512) is "strongly discouraged" by RFC 2104, section 3 but stays accepted, because deployments do key HS384 and HS512 with 32 bytes. It emits an E_USER_WARNING unless you acknowledge it:

use Cose\Algorithm\Mac\HS512;

$algorithm = HS512::create(acknowledgeShortKey: true);

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

To fail hard on a short key today, validate it before handing it to the algorithm:

use Cose\Algorithm\Mac\HS256;
use Cose\Key\SymmetricKey;
use Cose\Key\SymmetricKeyValidator;

$algorithm = HS256::create();
$key = SymmetricKey::create($data);

// Throws an InvalidArgumentException when the key is shorter than 32 bytes
SymmetricKeyValidator::create($algorithm->minimumKeyLength())->check($key);

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

Signature Verification Contract

Cose\Algorithm\Signature\Signature::verify() is total for every condition the governing specifications define as an "invalid signature" outcome. A malformed, truncated, over-long or out-of-range signature, and key material that the crypto layer cannot decode — a point that is not on the named curve, a public key that is not a valid group element — all return false. No PHP warning is raised on the way.

It throws an InvalidArgumentException in one case only: the key cannot be used with the algorithm at all, i.e. its key type or its curve does not match. Structurally invalid key components — an empty or zero RSA modulus, an x, y or d whose length does not fit the curve — are rejected earlier, by the Key constructors, so the exception is raised when the key is first seen rather than at every verification.

use Cose\Key\Key;
use InvalidArgumentException;

try {
    // Throws only when $key is an RSA key, an EC key on another curve, …
    $key = Key::createFromData($credentialPublicKey);
} catch (InvalidArgumentException $e) {
    // The credential cannot be used with this algorithm: reject it at registration.
}

// From here on, verification is a plain boolean, whatever the client sent.
$isValid = $algorithm->verify($data, $key, $signature);

sign() throws an InvalidArgumentException when the key is public, when the crypto layer cannot load it, or when the signature operation itself fails, for instance for an RSA modulus too short for the digest.

Key Parameter Forms

RFC 9052 and RFC 9053 type kty and crv as tstr / int, so the same key reaches this library under several shapes. The Key classes settle them all at construction time:

  • a key type or a curve given as the numeric string spomky-labs/cbor-php produces when it decodes a CBOR integer ('2', '-1') is stored as the integer it denotes, so Key::type() always compares equal to Key::TYPE_EC2 and friends, whether the key was decoded from CBOR or built by hand;
  • a key type may also be given by name: EC, OKP, RSA or oct;
  • a curve may be given by name — P-256, P-384, P-521, secp256k1, brainpoolP256r1 and so on. curve() returns the form the key carries, and Ec2Key::curveId() / OkpKey::curveId() return the value of the IANA COSE Elliptic Curves registry whatever that form is. The algorithm classes compare the latter, so a key that names its curve signs and verifies exactly like the same key that numbers it.
use Cose\Key\Ec2Key;

$key = Ec2Key::create([
    Ec2Key::TYPE => Ec2Key::TYPE_EC2,
    Ec2Key::DATA_CURVE => Ec2Key::CURVE_NAME_SECP256K1, // or Ec2Key::CURVE_P256K
    Ec2Key::DATA_X => $x,
    Ec2Key::DATA_Y => $y,
]);

$key->curve();   // 'secp256k1', as supplied
$key->curveId(); // 8, the registry value

Curve 8 is named secp256k1 by RFC 8812, section 4.2. Ec2Key::CURVE_NAME_P256K ('P-256K'), the spelling of a draft that was renamed before its first revision, is deprecated but still accepted.

Anything else — a float, a numeric string that is not an integer, a name no registry defines, an x that is not a byte string — is refused by the constructor with an InvalidArgumentException, before any of it is used.

Validating RSA Keys

The RSA algorithms reject, on their own, any key whose public parameters are not those RFC 8017, section 3.1 defines: an odd modulus and a public exponent that is an odd integer between 3 and n - 1. sign() throws and verify() returns false for such a key; nothing has to be done to get that behaviour.

The modulus length is a different matter. 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.

Both bounds are applied automatically, before the algorithm computes anything with the key.

The upper bounds are not negotiable: every RSA algorithm rejects a key whose modulus is longer than 16384 bits or whose public exponent is longer than 256 bits. verify() returns false for such a key and sign() throws.

The minimum modulus length is applied too, with RsaKeyValidator::create(), so that nothing has to be done to get the bound RFC 8230 requires. Because legacy authenticators holding 1024 bit keys still exist, a key below it only emits an E_USER_WARNING for now:

use Cose\Algorithm\Signature\RSA\RS256;

// Warns: "The RSA key does not satisfy RFC 8230 section 6.1: The modulus of the key is 1024 bits long; …"
// The signature is still verified, so no deployment breaks on upgrade.
$isValid = RS256::create()->verify($data, $weakKey, $signature);

As of the next major version, that warning becomes an InvalidArgumentException on sign() and a false on verify().

To keep accepting weaker keys, hand the algorithm a validator carrying the bound you actually accept. Writing the bound down is the acknowledgement: a key below it is still refused, right away and with an exception, because you chose that bound.

use Cose\Algorithm\Signature\RSA\RS256;
use Cose\Key\RsaKeyValidator;

// 1024 bit keys accepted silently; 512 bit ones still rejected
$algorithm = RS256::create(RsaKeyValidator::create(minimumModulusLength: 1024));

// The other way round: a stricter policy than the RFC, enforced now rather than in the next major version
$algorithm = RS256::create(RsaKeyValidator::create(minimumModulusLength: 3072, maximumModulusLength: 8192));

Every RSA algorithm takes it: RS256, RS384, RS512, PS256, PS384 and PS512 as their only argument, RS1 after its acknowledgeInsecureAlgorithm flag — RS1::create(true, RsaKeyValidator::create(minimumModulusLength: 1024)).

The validator can also be run on its own, on a key you are about to store:

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
}

check() and isValid() also cover the public parameter constraints described above. They are available on their own, without any modulus length policy:

// Throws an InvalidArgumentException unless the modulus is odd and 3 <= e < n
RsaKeyValidator::checkPublicParameters($key);

Verifying a Signature Made by a Certificate

WebAuthn Level 3 §8.2 to §8.4 ask a relying party to verify a packed (x5c), TPM or android-key attestation statement "with the algorithm specified in alg", against the key of the attestation certificate. Going through Algorithms::getOpensslAlgorithmFor() and openssl_verify() only reaches the algorithms an OPENSSL_ALGO_* digest can describe — ECDSA and RSASSA-PKCS1-v1_5 — because that digest implies PKCS #1 v1.5 padding; RSASSA-PSS, EdDSA, Ed25519 and Ed448 cannot be expressed that way at all.

Cose\Algorithm\Signature\CertificateSignatureVerifier takes the other route: the key of the certificate becomes a Cose\Key\Key, and the Signature class registered for the identifier verifies with it.

use Cose\Algorithm\Manager;
use Cose\Algorithm\Signature\CertificateSignatureVerifier;
use Cose\Algorithm\Signature\ECDSA\ES256;
use Cose\Algorithm\Signature\RSA\PS256;

$manager = Manager::create()->add(ES256::create(), PS256::create());
$verifier = CertificateSignatureVerifier::create($manager);

$isValid = $verifier->verify($alg, $certificatePem, $data, $signature);

The set of acceptable algorithms is the Manager the operator built, not a constant of this library: an alg that comes from the wire cannot select a verifier that was never registered. Nothing is configured twice either — it is the registered instance that verifies, so the minimum modulus length an RSA algorithm was created with applies unchanged to the key of the certificate.

verify() returns false for every signature the algorithm rejects, and throws an InvalidArgumentException when the certificate cannot be read, when no signature algorithm is registered for the identifier, or when the key of the certificate cannot be used with that algorithm.

The key alone is enough when the certificate is not at hand — verifySubjectPublicKeyInfo() takes a SubjectPublicKeyInfo, and Cose\Key\PublicKeyLoader exposes the conversion on its own. Both accept PEM or DER.

use Cose\Key\PublicKeyLoader;

$key = PublicKeyLoader::fromCertificate($certificatePem);
$key = PublicKeyLoader::fromSubjectPublicKeyInfo($spkiPem);

Registering Algorithms

Cose\Algorithm\Manager registers each algorithm under the identifier it declares, and Cose\Algorithm\ManagerFactory registers algorithms under aliases so that a Manager can be generated from a subset of them.

A later registration for an identifier (or an alias) that is already taken replaces the earlier one. When the replacement is an instance of another class, that is a misconfiguration rather than an intent — list() keeps reporting a single entry, and which verifier answers for the identifier is decided by registration order alone — so an E_USER_WARNING is emitted. Registering the same class twice stays silent, so a container that autoconfigures an algorithm more than once keeps working.

As of the next major version, a duplicate bound to a different class will throw an InvalidArgumentException, and an explicit replace() will be the way to override a registration on purpose.

Performance

ext-gmp (recommended) or ext-bcmath is worth installing, but no longer required for RSA verification to be cheap: RsaKey::asPem(), RsaKeyValidator and the public operation of every RSA algorithm are computed without brick/math. Signing with RSASSA-PSS (PS256, PS384, PS512) still uses it for the blinding of the private exponentiation, and falls back to a pure PHP calculator when neither extension is loaded — which is the configuration of the stock php and php-fpm Docker images.

Testing

Run the test suite in the project QA container (nothing to install):

castor phpunit

Or directly, on a host that provides PHPUnit 11 as phpunit-11:

composer test

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

Optional, depending on what you use:

  • ext-sodium — required by every Ed25519 algorithm (EdDSA -8, Ed25519 -8 and -19, Ed256 -260, Ed512 -261) and to recompute an OKP public key from its private key. Sodium ships with PHP and is enabled by default, but a build can leave it out: creating one of these algorithms then throws a RuntimeException instead of reporting valid signatures as invalid. Call EdDSA::isSupported() when the platform is not known in advance.
  • spomky-labs/cbor-php ^3.3.4 — required by the COSE tag classes (Sign, Encrypt, Mac). Versions below 3.3.4 are rejected by a conflict entry, because that decoder is what enforces the RFC 9052 header-map rules.
  • ext-gmp or ext-bcmath — see Performance.

Contributing

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

For security vulnerabilities, do not open an issue: report them privately through GitHub private vulnerability reporting or by e-mail to security [at] spomky-labs.com. See SECURITY.md.

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:

License

This software is released under the MIT License.

Credits

Maintained by Florent Morselli and contributors.


Made with ❤️ for the PHP community