Skip to content

Provided features

The library implements COSE (CBOR Object Signing and Encryption) as defined in RFC 9052 and RFC 9053: the COSE key types, the signature, MAC, content encryption and key management algorithms, the cryptographic structures a signature, a MAC or an encryption is computed over, and the header rules that decide what a message says.

The six COSE message types themselves come from spomky-labs/cbor-php 3.4.0 or later, as CBOR\Tag\CoseSign1Tag and its siblings; this library owns what RFC 9052 reads into them.

What it implements

Specification What the library does with it
RFC 9052 Structures and process: the Sig_structure, MAC_structure and Enc_structure, the header rules, external_aad, detached content
RFC 9053 Initial algorithms: signatures, HMAC, AES-CBC-MAC, the AEAD content encryption algorithms, the key management algorithms (direct, HKDF, AES Key Wrap, ECDH) and the key types
RFC 8230 RSASSA-PSS (PS256, PS384, PS512) and the RSA key type
RFC 8812 RSASSA-PKCS1-v1_5 (RS256, RS384, RS512, RS1) and ECDSA with secp256k1 (ES256K)
RFC 9864 Fully-specified algorithm identifiers
RFC 9596 The typ (type) header parameter
RFC 9597 CWT Claims in COSE headers
RFC 9054 The hash algorithms, as a registry of their own
RFC 9679 The COSE Key Thumbprint
RFC 9360 The header parameters carrying and referencing X.509 certificates
RFC 9995 The hash envelope
RFC 9338 Countersignatures, version 2, labels 11 and 12
RFC 9964 ML-DSA for JOSE and COSE: ML-DSA-44/65/87 and the AKP key type
RFC 9942 Receipts: the receipts, vds and vdp header parameters and the RFC9162_SHA256 verifiable data structure
RFC 9921 RFC 3161 timestamp tokens, carried and bound to the message, not validated

Where to start

What it leaves to the application

The library computes and checks cryptography over the structures the RFCs define. Several decisions are not cryptographic, and it does not make them for you:

  • Which algorithm is acceptable for a given message. A verification confirms the signature made by the algorithm the message names; deciding that the algorithm was allowed to sign it is a separate step. See What the application must check.
  • Whether a certificate is trusted. The X.509 header parameters are read and the certificate they carry can be turned into a key, but no chain is built or validated and no network call is made. See X.509 header parameters.
  • Whether a claim is acceptable. A CWT is verified as a COSE message; the claims inside it are yours to check. See CBOR Web Tokens.
  • Whether a timestamp token or a receipt comes from an authority you trust. The binding between the token and the message is checked; the trust in the issuer is not. See Timestamp tokens and Receipts.

Each of those pages ends with a section saying where the library stops.

References