COSE 与 CWT 解码器

JOSE for CBOR

COSE — CBOR Object Signing and Encryption, RFC 9052 with the algorithms of RFC 9053 — does for compact binary data what JWS and JWE do for JSON: it signs, MACs and encrypts CBOR. It is everywhere small messages matter: the public key of every passkey is a COSE_Key inside the WebAuthn authenticator data, ISO 18013-5 mobile driving licences are signed with COSE_Sign1, the EU Digital COVID Certificate was a CWT, and IoT protocols such as ACE-OAuth and EDHOC build on it. A CBOR Web Token (RFC 8392) is the JWT of this world: a claims set with integer keys (1 iss, 2 sub, 3 aud, 4 exp, 5 nbf, 6 iat, 7 cti, 8 cnf) inside a COSE_Sign1 or COSE_Mac0, optionally wrapped in CBOR tag 61.

How the decoder reads your input

It accepts hex, base64 or base64url and decodes the CBOR, keeping the original bytes of every item: digests and signatures are computed over bytes exactly as received, never over a re-encoding. Then it recognises what it is looking at:

• a tagged COSE message — tag 18 COSE_Sign1, 98 COSE_Sign, 17 COSE_Mac0, 97 COSE_Mac, 16 COSE_Encrypt0, 96 COSE_Encrypt — or an untagged one, when you choose its type (an untagged array carries no type, RFC 9052 §2);
• a CWT, tagged 61 or recognised by its claims, including a CWT nested inside another (an encrypted or MACed envelope);
• a bare claims set, a COSE_Key or a COSE_KeySet.

Every header parameter is named from the IANA COSE registries and shown with its bucket: protected headers are part of what is signed, unprotected ones are not, which matters — an alg placed only in the unprotected bucket can be changed by anyone. Claims are named from the CWT registry, NumericDates are shown as UTC dates, and the whole structure is printed in CBOR diagnostic notation and as annotated hex.

What gets signed

A COSE signature is not computed over the message bytes. The signer builds a Sig_structure (§4.4): the context string Signature1 (or Signature for each signer of a COSE_Sign), the protected header bytes, any external additional authenticated data the application binds in, and the payload — and signs its CBOR encoding. A MAC is computed over a MAC_structure the same way (§6.3). So two things the decoder asks for are not in the message itself: the external AAD, when the protocol uses it, and the payload, when it is detached (nil in the message, sent separately).

Signatures are checked with the key you paste: a COSE_Key, a JWK, a PEM public key or an X.509 certificate — or the certificate in the message's own x5chain header, which the decoder lists. ES256/384/512 and ES256K (raw r‖s per RFC 9053, not DER), EdDSA with Ed25519 and Ed448, PS256/384/512 and RS256/384/512 are supported; HMAC 256/64, 256/256, 384/384 and 512/512 with the secret you give. Encrypted structures are described — algorithm, recipients, key IDs — but never decrypted.

The examples come from RFC 8392 Appendix A — a signed and a MACed CWT and their claims set, valid in October 2015 — and from the COSE Working Group's example suite. The mobile driving licences built on COSE_Sign1 have their own inspector: the mdoc inspector.