Validate COSE key metadata

docs/API-Reference.md

@@ -364,7 +364,7 @@ Encode a COSE key to CBOR format.
 ### wc_CoseKey_Encode_ex
 
 ```c
-int wc_CoseKey_Encode_ex(WOLFCOSE_KEY* key, uint8_t* buf, size_t bufSz,
+int wc_CoseKey_Encode_ex(const WOLFCOSE_KEY* key, uint8_t* buf, size_t bufSz,
                          size_t* outLen, uint32_t flags);
 ```
 
@@ -473,20 +473,22 @@ Decode a COSE key from CBOR format.
 **Parameters:**
 | Name | Description |
 |------|-------------|
-| `key` | Pointer to COSE key structure (with pre-allocated wolfCrypt key) |
+| `key` | Initialized COSE key structure; may have a wolfCrypt key attached |
 | `buf` | Input CBOR buffer |
 | `bufSz` | Size of input buffer |
 
 **Returns:** `WOLFCOSE_SUCCESS` or error code
 
-Attach the wolfCrypt key with `wc_CoseKey_SetEcc()`, `wc_CoseKey_SetEd25519()`,
+Attach a wolfCrypt key with `wc_CoseKey_SetEcc()`, `wc_CoseKey_SetEd25519()`,
 `wc_CoseKey_SetEd448()`, `wc_CoseKey_SetRsa()`, `wc_CoseKey_SetMlDsa()`, or
-`wc_CoseKey_SetSymmetric()`. These record which wolfCrypt object is attached;
-assigning the `key.*` union directly does not. Only attachments recorded by a
-setter are preserved across decode; an untyped `key.*` union is cleared before
-parsing, and no key material is imported.
-
-The decoded `kty`/`crv` must name the attached key type or
+`wc_CoseKey_SetSymmetric()`. These record which wolfCrypt object is attached.
+Without an attachment, supported asymmetric metadata is still validated and
+returned, but key material is not imported. Assigning the `key.*` union
+directly records no attached type and imports nothing. Only attachments
+recorded by a setter are preserved across decode; an untyped `key.*` union is
+cleared before parsing.
+
+When a key is attached, the decoded `kty`/`crv` must name that key type or
 `WOLFCOSE_E_COSE_KEY_TYPE` is returned before any importer runs. To learn which
 key type a buffer holds before attaching anything, use
 [`wc_CoseKey_PeekInfo()`](#wc_cosekey_peekinfo).
@@ -527,10 +529,8 @@ int wc_CoseKey_PeekInfo(const uint8_t* in, size_t inSz,
 Read `kty`, `alg`, `crv`, and `kid` out of a `COSE_Key` buffer without
 importing any key material and without needing a wolfCrypt key object.
 
-`wc_CoseKey_Decode()` requires the caller to have attached a key of the
-matching type up front and returns `WOLFCOSE_E_COSE_KEY_TYPE` otherwise, so a
-parser that accepts more than one key type would have to guess and retry.
-Peek first, then attach once:
+When asymmetric key material is to be imported, peek first to identify its
+type, then attach the matching wolfCrypt object once:
 
 ```c
 WOLFCOSE_KEY_INFO info;

include/wolfcose/wolfcose.h

@@ -937,7 +937,7 @@ WOLFCOSE_API int wc_CoseKey_Encode(WOLFCOSE_KEY* key, uint8_t* out,
  * \param flags   Bitmask of WOLFCOSE_KEY_* output options.
  * \return WOLFCOSE_SUCCESS or negative error code.
  */
-WOLFCOSE_API int wc_CoseKey_Encode_ex(WOLFCOSE_KEY* key, uint8_t* out,
+WOLFCOSE_API int wc_CoseKey_Encode_ex(const WOLFCOSE_KEY* key, uint8_t* out,
                                        size_t outSz, size_t* outLen,
                                        uint32_t flags);
 
@@ -1033,10 +1033,9 @@ typedef struct WOLFCOSE_KEY_INFO {
 /**
  * \brief Read kty/alg/crv/kid from a COSE_Key buffer without importing it.
  *
- * wc_CoseKey_Decode() needs a wolfCrypt key of the matching type attached up
- * front and returns WOLFCOSE_E_COSE_KEY_TYPE otherwise, so a parser that
- * accepts more than one key type would have to guess and retry. This reads
- * the metadata first so the caller can attach the right key object once.
+ * wc_CoseKey_Decode() can validate metadata without an attached wolfCrypt
+ * key. When asymmetric key material is to be imported, this reads the
+ * metadata first so the caller can attach the right key object once.
  *
  * Nothing is imported, no key object is needed, and \p in is not modified.
  * The same structural checks wc_CoseKey_Decode() applies are applied here
@@ -1057,11 +1056,14 @@ WOLFCOSE_API int wc_CoseKey_PeekInfo(const uint8_t* in, size_t inSz,
 /**
  * \brief Decode a CBOR COSE_Key map into a WOLFCOSE_KEY structure.
  *        For symmetric keys, pointers reference the input buffer.
- *        For ECC/Ed25519, caller must attach a key struct via
- *        wc_CoseKey_SetEcc()/SetEd25519()/SetEd448()/SetRsa()/SetMlDsa();
- *        assigning key.* directly records no type and imports nothing.
- *        Only attachments recorded by a wc_CoseKey_Set*() API are preserved
- *        across decode; an untyped key union is cleared before parsing.
+ *        Attach a matching asymmetric key object with wc_CoseKey_SetEcc(),
+ *        SetEd25519(), SetEd448(), SetRsa(), SetMlDsa(), or SetSymmetric() to
+ *        attach key material. Without an attachment, supported asymmetric
+ *        metadata is still validated and returned, but key material is not
+ *        imported. Assigning key.* directly records no type and imports
+ *        nothing. Only attachments recorded by a wc_CoseKey_Set*() API are
+ *        preserved across decode; an untyped key union is cleared before
+ *        parsing.
  *        A decoded kty/crv that does not match the attached type returns
  *        WOLFCOSE_E_COSE_KEY_TYPE before any import runs.
  *        Keys containing key_ops return WOLFCOSE_E_UNSUPPORTED before any
@@ -1072,8 +1074,8 @@ WOLFCOSE_API int wc_CoseKey_PeekInfo(const uint8_t* in, size_t inSz,
  *        or a non-transactional callback or hardware backend, private EC2
  *        decode returns WOLFCOSE_E_UNSUPPORTED before importing key
  *        material.
- * \param key   Key structure (should be initialized, with wolfCrypt key
- *              attached for asymmetric types).
+ * \param key   Initialized key structure. Attach a wolfCrypt key when
+ *              asymmetric key material should be imported.
  * \param in    Input CBOR buffer.
  * \param inSz  Input buffer size.
  * \return WOLFCOSE_SUCCESS or negative error code.

src/wolfcose_internal.h

@@ -657,10 +657,13 @@ WOLFCOSE_LOCAL void wolfCose_EccPrivateImportRollback(ecc_key* ecc,
 WOLFCOSE_LOCAL void wolfCose_HdrClearOnFail(int ret, WOLFCOSE_HDR* hdr);
 #endif
 
-#if defined(WOLFCOSE_MAC0_VERIFY) || defined(WOLFCOSE_MAC_VERIFY)
+#if defined(WOLFCOSE_MAC0_VERIFY) || defined(WOLFCOSE_MAC_VERIFY) || \
+    (defined(WOLFCOSE_KEY_DECODE) && defined(WOLFCOSE_HAVE_MLDSA) && \
+     !defined(WOLFSSL_MLDSA_NO_MAKE_KEY))
+#define WOLFCOSE_NEED_CONSTANT_COMPARE
 /* ConstantCompare -- defined in wolfcose_util.c */
-WOLFCOSE_LOCAL int wolfCose_ConstantCompare(const byte* a, const byte* b,
-                                     word32 length);
+WOLFCOSE_LOCAL int32_t wolfCose_ConstantCompare(const byte* a, const byte* b,
+                                                 word32 length);
 #endif
 
 #ifdef __cplusplus