|
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
- 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> |
||
|---|---|---|
| .. | ||
| src | ||
| CODE_OF_CONDUCT.md | ||
| composer.json | ||
| LICENSE | ||
| README.md | ||
| RELEASES.md | ||
| SECURITY.md | ||
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
✅ RFC 9052 Cryptographic Structures
Sig_structure:Signature1(§4.4) andSignature, which also covers the signer's own protected headerMAC_structure:Mac0StructureandMacStructure(§6.3) — a MAC tag covers this, never the bare payloadEnc_structure:Encrypt0Structure,EncryptStructureandRecipientStructure(§5.3)- Each takes the optional
external_aad, defaulting to the zero-length byte string the RFC prescribes
✅ RFC 9052 Header and Structure Rules
CoseHeadersreads 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 lookupCoseSignatureandCoseRecipientare the checked views over thesignaturesandrecipientslists ([+ ...])- 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), plusCwtTag(61), all registered in the default decoder- The
Cose\...Tagclasses 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) andkey_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
algis the one expected for that key, and refusing anycritlabel 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.phpruns 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, andcreate()— as above — when the bytes have to travel verbatim.examples/01-sign1.phpis the whole round trip, key generation included, and runs as it stands.
Documentation
- Examples - A runnable program per topic;
php examples/01-sign1.phpto 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) andCose\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) andEd512(-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 thedom2prefix 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,Ed512is not Ed448 and rejects an Ed448 key; EdDSA with Curve448 isCose\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_WARNINGunless you explicitly acknowledge the risk:use Cose\Algorithm\Signature\RSA\RS1; $algorithm = RS1::create(acknowledgeInsecureAlgorithm: true);The same acknowledgement applies to
Algorithms::getOpensslAlgorithmFor()andAlgorithms::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, soKey::type()always compares equal toKey::TYPE_EC2and friends, whether the key was decoded from CBOR or built by hand; - a key type may also be given by name:
EC,OKP,RSAoroct; - a curve may be given by name —
P-256,P-384,P-521,secp256k1,brainpoolP256r1and so on.curve()returns the form the key carries, andEc2Key::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 aRuntimeExceptioninstead of reporting valid signatures as invalid. CallEdDSA::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 aconflictentry, 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