1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
//! No std CBOR Object Signing and Encryption, Cose [RFC 9052 ](https://datatracker.ietf.org/doc/html/rfc9052)/ [RFC 9053](https://datatracker.ietf.org/doc/html/rfc9053).
//!
//!
//! This crate provides lightweight, `no_std`-friendly methods and structure for **decoding** COSE
//! message types (e.g. `CoseSign`, `CoseSign1`, `CoseMac`, `CoseMac0`) using [minicbor](https://crates.io/crates/minicbor).
//!
//! It is inspired by [cose-rust](https://crates.io/crates/cose-rust) but targeted at constrained / embedded environments:
//! the emphasis is on borrowed decoding, minimal allocations and lazy parsing.
//!
//! The implementation targets the COSE/CBOR stack specified by:
//! - [RFC 9052 — COSE](https://datatracker.ietf.org/doc/html/rfc9052)
//! - [RFC 9053 — CBOR Object Signing and Encryption (COSE)](https://datatracker.ietf.org/doc/html/rfc9053)
//!
//! And supports the cryptographic profiles depicted in:
//! - [Cryptographic Algorithms for IoT (SUIT MTI draft)](https://datatracker.ietf.org/doc/html/draft-ietf-suit-mti/23/)
//!
//! ## Scope & goals
//! - **Decode-first**: focus on *decoding* COSE structures and exposing ergonomic Rust types to inspect and verify messages.
//! - **no_std-friendly**: designed to build on targets without `std` or `alloc`.
//!
//!
//! ## Cryptographic backends
//! Cryptographic verification is delegated to backend crates (enable via Cargo features).
//! Typical backends (links to crates):
//! - signature verification:
//! - [`p256`](https://crates.io/crates/p256) — P-256 / ECDSA support.
//! - [`ed25519-dalek`](https://crates.io/crates/ed25519-dalek) — Ed25519 signatures.
//! - [`hss_lms`](https://crates.io/crates/hbs-lms) — LMS (Leighton-Micali Signatures.
//! - MAC / digest:
//! - [`hmac`](https://crates.io/crates/hmac) — HMAC interface.
//! - [`sha2`](https://crates.io/crates/sha2) — SHA-2 family (SHA-256, SHA-384).
//!
//! ## Modularity and Feature Profiles
//!
//! This crate is designed to be highly modular: **each cryptographic backend and algorithm
//! is behind its own feature flag**. This allows users to compile only the code they
//! need, minimizing binary size — which is particularly important for `no_std` and embedded targets.
//!
//! ## SUIT MTI Profiles
//!
//! This crate provides predefined **cryptographic profiles** following the [SUIT MTI draft](https://datatracker.ietf.org/doc/draft-ietf-suit-mti/23/) for IoT device update verification.
//!
//! Each MTI profile is a **bundle of features** corresponding to the cryptographic algorithms and workflows recommended by SUIT:
//!
//! | Profile | Description | Features Enabled |
//! |---------|-------------|----------------|
//! | `suit-sha256-hmac` | HMAC/SHA-256 only | `sha256`, `hmac256`, `decrypt` |
//! | `suit-sha256-hmac-a128kw` | HMAC/SHA-256 + AES-128 Key Wrap | `sha256`, `hmac256`, `a128kw` |
//! | `suit-sha256-hmac-a256kw` | HMAC/SHA-256 + AES-256 Key Wrap | `sha256`, `hmac256`, `a256kw` |
//! | `suit-sha256-hmac-ecdh_es-a256kw` | HMAC/SHA-256 + ECDH-ES + AES-256 Key Wrap | `sha256`, `hmac256`, `ecdh_es`, `a256kw` |
//! | `suit-sha256-es256` | SHA-256 + ES256 signatures | `sha256`, `es256` |
//! | `suit-sha256-ed25519` | SHA-256 + Ed25519 signatures | `sha256`, `ed25519` |
//! | `suit-sha256-hsslms` | SHA-256 + HSS/LMS signatures | `sha256`, `hss_lms` |
//!
//! > **Note:** Using these profiles ensures all required features for a given cryptographic workflow are enabled automatically. This avoids subtle bugs where functions such as `decrypt_process` or HMAC verification are unavailable due to missing features.
//!
//! ---
//!
//! ## Example: HMAC Verification with AES-128 KW
//!
//! This example demonstrates how to verify a `CoseMac` using an A128 Key Wrap KEK
//! following the SUIT HMAC profile.
//!
//! ```rust
//! # #[cfg(all(feature = "hmac", feature = "aeskw256"))] {
//! use cose_minicbor::cose::CoseMac;
//! use cose_minicbor::cose_keys::{CoseAlg, CoseKey, CoseKeySetBuilder, KeyOp, KeyType};
//! use hex_literal::hex;
//! use minicbor::Decode;
//!
//! // 1. Build a COSE Key Set containing a KEK for AES-128 KW
//! let mut builder: CoseKeySetBuilder<200> = CoseKeySetBuilder::try_new().unwrap();
//!
//! let mut key = CoseKey::new(KeyType::Symmetric);
//! key.alg(CoseAlg::A128KW);
//! key.k(&hex!("c1e60d0db5c6cbdac37e8473b412f6b0")).unwrap();
//! key.kid(b"our-secret");
//! key.key_op(KeyOp::UnwrapKey);
//!
//! builder.push_key(key).unwrap();
//! let key_set_bytes = builder.into_bytes().unwrap();
//!
//! // 2. Decode a COSE Mac from CBOR (example)
//! let mac_bytes = cbor_diag::parse_diag("
//! [
//! /protected/ h'A10105',
//! /unprotected/{},
//! /payload/ h'546869732069732074686520636F6E74656E742E',
//! /tag/ h'2bdcc89f058216b8a208ddc6d8b54aa91f48bd63484986565105c9ad5a6682f6',
//! /recipients/ [
//! [
//! /protected/ h'',
//! /unprotected/ {
//! /alg/ 1: -3,
//! /kid/ 4: h'6F75722D736563726574'
//! },
//! /ciphertext/ h'45f19543a4ea912e07fa280d14f7397da96f446a0246d983cd3457e038aec3e21fc286f139d1edd2'
//! ]
//! ]
//!
//! ]")
//! .unwrap()
//! .to_bytes();
//!
//! let mac: CoseMac = minicbor::decode(&mac_bytes).expect("Invalid CoseMac format");
//!
//! // 3. Verify the MAC using the COSE Key Set
//! mac.suit_verify_mac(None, &key_set_bytes)
//! .expect("HMAC verification failed");
//! # }
//! ```
//!
//! ## License
//! SPDX: MIT
pub use CoseError;