CBOR Object Signing and Encryption (COSE)
obsoleted by
Extracted elements (30)
COSE separates MAC structures from signature structures (unlike some prior formats), because their security properties differ: signatures provide non-repudiation, while MACs require a shared secret and only authenticate to parties holding that secret. The separation prevents misuse and simplifies security analysis.
COSE uses binary (bstr) encodings for cryptographic values rather than base64url strings as in JOSE/JSON. This reduces message size and eliminates base64 encoding/decoding overhead, which is significant for constrained IoT devices targeted by this specification.
The authentication tag for AEAD encryption is combined with the ciphertext in COSE (rather than as a separate field as in some JOSE structures). This simplifies processing and reflects the fact that AEAD algorithms inherently output a combined ciphertext+tag.
Implementations SHOULD use a deterministic version of ECDSA such as RFC 6979 to avoid relying on a random number generator for the per-message value 'k'. Biased or reused values of 'k' can be attacked and collisions lead to private key leakage.
Labels in each COSE header map MUST be unique; a message with duplicate labels MUST be rejected as malformed. Applications SHOULD verify no label appears in both protected and unprotected headers. When a label appears in both, attributes MUST be taken from the protected bucket.
The 'alg' header parameter (label 1) MUST be authenticated where the ability to do so exists, either by placing it in the protected header bucket or via externally supplied data. This prevents algorithm substitution attacks against COSE messages.
The 'crit' header parameter (label 2) MUST be placed in the protected header bucket and its array MUST contain at least one value. If a label listed in 'crit' is absent from the protected bucket, this is a fatal error in message processing.
The 'Initialization Vector' (label 5) and 'Partial Initialization Vector' (label 6) parameters MUST NOT both be present in the same security layer. The full IV is computed by left-padding the Partial IV with zeros to IV length and XORing with the context Base IV.
The 'kty' field MUST be present in every COSE_Key. Implementations MUST verify that the key type is appropriate for the algorithm being processed. If the 'alg' field is present, the application MUST verify it matches the algorithm in use, and MUST NOT use the key if they differ.
When using a COSE key with ECDSA, the 'kty' field MUST be 'EC2'; if 'alg' is present it MUST match the algorithm; if 'key_ops' is present it MUST include 'sign' for signing operations and 'verify' for verification. Implementations must check that the curve matches the algorithm.
A COSE_Key is a CBOR map with required field 'kty' (label 1) and optional fields: 'kid' (2, bstr), 'alg' (3, tstr/int), 'key_ops' (4, array), and 'Base IV' (5, bstr). A COSE_KeySet is a CBOR array of one or more COSE_Key objects and MUST contain at least one element.
COSE defines six message structures, each identified by a CBOR tag: COSE_Sign (98), COSE_Sign1 (18), COSE_Encrypt (96), COSE_Encrypt0 (16), COSE_Mac (97), and COSE_Mac0 (17). Messages may be tagged or untagged; the type can alternatively be identified by context, the 'cose-type' media type parameter, or CoAP Content-Format.
COSE supports five content key distribution classes: direct (CEK is or is derived from a pre-shared secret), symmetric key-encryption keys (key wrap), key agreement (ECDH + KDF), key transport (recipient's public key), and password-based. Only direct, key wrap, and key agreement are defined in RFC 8152.
Counter signatures allow a second party to sign an existing COSE object (e.g., a timestamp proof). They may appear as an unprotected attribute in COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient, COSE_Encrypt0, COSE_Mac, or COSE_Mac0. Only signature-with-appendix algorithms may be used for counter signatures.
Externally supplied data allows applications to authenticate bytes not carried in the COSE object (e.g., CoAP option fields). Applications must define unambiguous construction of the external_aad byte string, addressing field ordering, fixed-width encoding, or length prefixing to prevent collisions.
The Enc_structure provides the AAD byte stream for AEAD encryption: [context: tstr, protected: bstr, external_aad: bstr]. Context strings distinguish the layer: 'Encrypt0', 'Encrypt', 'Enc_Recipient', 'Mac_Recipient', or 'Rec_Recipient'. AE algorithms require an empty protected header and no external AAD.
The MAC_structure canonicalizes the data to be MACed: [context: 'MAC'/'MAC0', protected: bstr, external_aad: bstr, payload: bstr]. Verification is performed by recomputing the MAC over the reconstructed MAC_structure and comparing it to the 'tag' field.
The Sig_structure canonicalizes the data to be signed as a CBOR array [context: tstr, body_protected: bstr, sign_protected?: bstr, external_aad: bstr, payload: bstr]. The context string is 'Signature', 'Signature1', or 'CounterSignature'; the sign_protected field is omitted for COSE_Sign1.
RFC 8152 creates the COSE Algorithms registry with initial entries for ECDSA (ES256=-7, ES384=-35, ES512=-36), EdDSA (-8), HMAC variants, AES-GCM, AES-CCM, AES-CBC-MAC, ChaCha20/Poly1305, HKDF, AES Key Wrap, and ECDH variants. It also creates the COSE Key Types, COSE Key Common Parameters, COSE Key Type Parameters, and COSE Elliptic Curves registries.
RFC 8152 creates the COSE Header Parameters registry with initial entries alg (1), crit (2), content type (3), kid (4), IV (5), Partial IV (6), counter signature (7). It also creates the COSE Header Algorithm Parameters registry for algorithm-specific header parameters.
RFC 8152 registers CBOR tags 98, 18, 96, 16, 97, and 17 for COSE_Sign, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, and COSE_Mac0 respectively. It also registers 'application/cose' and 'application/cose-key' media types and CoAP Content-Format values.
An ECDSA substitution attack can substitute a different curve during signature validation, potentially finding a second message with the same signature under the new curve. Implementations must bind and verify the curve parameter from the key; the 'kty' and curve fields in COSE_Key provide this binding.
Many AEAD encryption algorithms (e.g., AES-GCM) lose all security if the same (key, IV) pair is used twice. The Base IV and Partial IV mechanism requires careful application design: when the same key is shared by multiple senders, the IV space must be explicitly partitioned to prevent reuse.
All COSE message structures are CBOR arrays whose first two elements are: (1) the protected header bucket encoded as a CBOR map serialized into a bstr, and (2) the unprotected header bucket as a plain CBOR map. Senders SHOULD encode an empty protected header as a zero-length bstr rather than a zero-length map (h'a0').
COSE_Encrypt is a CBOR array [Headers, ciphertext: bstr/nil, recipients: [+COSE_recipient]]. COSE_recipient has the same structure with an optional nested recipients field, enabling layered key distribution. CBOR tag 96 marks a tagged COSE_Encrypt.
COSE_Encrypt0 is a CBOR array [Headers, ciphertext: bstr/nil] for single-recipient encryption where the key is known implicitly. CBOR tag 16 marks a tagged COSE_Encrypt0. When a key must be identified to the recipient, COSE_Encrypt should be used instead.
COSE_Mac is a CBOR array [Headers, payload: bstr/nil, tag: bstr, recipients: [+COSE_recipient]] with CBOR tag 97. COSE_Mac0 is [Headers, payload: bstr/nil, tag: bstr] with CBOR tag 17, for the implicit-key case.
COSE_Sign is a CBOR array [Headers, payload: bstr/nil, signatures: [+COSE_Signature]]. COSE_Signature is [Headers, signature: bstr]. CBOR tag 98 marks a tagged COSE_Sign. Algorithms MUST specify padding if the signature value is not a multiple of 8 bits.
COSE_Sign1 is a CBOR array [Headers, payload: bstr/nil, signature: bstr] for single-signer messages. CBOR tag 18 marks a tagged COSE_Sign1. It cannot be converted to/from COSE_Sign because the signature computation includes the structure context string.
ECDSA signatures encode the (R, S) integer pair as concatenated fixed-width byte strings: Signature = I2OSP(R, n) || I2OSP(S, n) where n = ceiling(key_length / 8). Defined algorithm identifiers: ES256 (value -7, SHA-256), ES384 (-35, SHA-384), ES512 (-36, SHA-512).