cose2 0.3.0

A Rust library for CBOR Object Signing and Encryption (COSE, RFC 9052) and CBOR Web Token (CWT, RFC 8392), built on cbor2.
Documentation 
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

//! `cose2` — CBOR Object Signing and Encryption (COSE, RFC 9052) and CBOR
//! Web Token (CWT, RFC 8392) for Rust, built on [`cbor2`].
//!
//! This crate models COSE structures (messages, headers, keys) and CWT
//! claims, and delegates cryptography to caller-supplied implementations of
//! the [`Signer`], [`Verifier`], [`Macer`] and [`Encryptor`] traits — so it
//! ships no cryptographic dependencies in its default feature set.
//! Top-level COSE messages use named Rust structs with `#[cbor(array)]` to keep
//! the COSE array wire shape, and encode with their registered CBOR tags
//! through `#[derive(cbor2::Cbor)]`. CWT claims likewise encode with their
//! registered CBOR tag. Decode helpers still accept untagged messages and claim
//! maps for compatibility.
//! Headers reject malformed `crit` parameters and protected/unprotected bucket
//! label collisions. Critical header parameters (`crit`) that an application
//! must understand are validated structurally on decode; applications that
//! process untrusted input should additionally call
//! [`Header::ensure_crit_understood`] on each protected header to enforce the
//! RFC 9052 §3.1 rule that an unrecognised critical parameter is a fatal error.
//! Header accessors and the message layer read attributes from the protected
//! bucket first and then the unprotected bucket (RFC 9052 §3).
//! Keys enforce required `kty` values and non-empty `COSE_KeySet`s. Recipient
//! structures validate the RFC 9052 shape for known recipient algorithm
//! classes. Content-key distribution itself (key wrap, key transport, ECDH key
//! agreement, and the `Enc_Recipient` / `Mac_Recipient` / `Rec_Recipient`
//! recipient-layer cryptography of RFC 9053) is left to application code: this
//! crate models and validates the recipient structures but does not encrypt or
//! decrypt the content-encryption key.
//! Content encryption follows the AEAD construction of RFC 9052 §5.3; the
//! [`Encryptor`] trait always authenticates the `Enc_structure`, so the AE-only
//! construction of §5.4 (zero-length protected header, no external AAD) is not
//! directly modelled.
//! Encryption accepts either a full `IV`, or a `Partial IV` combined with
//! [`Encryptor::base_iv`], and never generates nonces internally.
//! Optional crypto backends are available behind feature flags; enable
//! `crypto-ring` or the aggregate `crypto` feature for a `ring`-based backend.
//!
//! # Example: COSE_Sign1 round trip
//!
//! ```
//! use cose2::{iana, Sign1Message, Signer, Verifier, Error};
//!
//! // A trivial (insecure) signer/verifier for illustration.
//! struct Demo;
//! impl Signer for Demo {
//!     fn alg(&self) -> Option<cose2::Label> { Some(iana::AlgorithmEdDSA.into()) }
//!     fn kid(&self) -> Option<&[u8]> { Some(b"key-1") }
//!     fn sign(&self, data: &[u8]) -> Result<Vec<u8>, Error> { Ok(data.to_vec()) }
//! }
//! impl Verifier for Demo {
//!     fn alg(&self) -> Option<cose2::Label> { Some(iana::AlgorithmEdDSA.into()) }
//!     fn verify(&self, data: &[u8], sig: &[u8]) -> Result<(), Error> {
//!         if sig == data { Ok(()) } else { Err(Error::verify("bad signature")) }
//!     }
//! }
//!
//! let mut msg = Sign1Message::new(Some(b"This is the content".to_vec()));
//! let encoded = msg.sign_and_encode(&Demo, None).unwrap();
//!
//! let verified = Sign1Message::verify_and_decode(&Demo, &encoded, None).unwrap();
//! assert_eq!(verified.payload.as_deref(), Some(&b"This is the content"[..]));
//! ```

#![forbid(unsafe_code)]
#![deny(rustdoc::broken_intra_doc_links)]

pub mod iana;

mod error;
mod header;
mod key;
mod label;
mod map;
pub mod tag;
mod traits;
mod util;

mod context;
mod encrypt;
mod encrypt0;
mod mac;
mod mac0;
mod recipient;
mod sign;
mod sign1;

#[cfg(feature = "crypto-ring")]
pub mod crypto;
pub mod cwt;

pub use error::Error;
pub use header::{is_understood_header, Header};
pub use key::{Key, KeySet};
pub use label::Label;
pub use map::CoseMap;
pub use traits::{EncryptionContext, Encryptor, Macer, Signer, Verifier};

pub use context::{KdfContext, PartyInfo, SuppPubInfo};
pub use encrypt::EncryptMessage;
pub use encrypt0::Encrypt0Message;
pub use mac::MacMessage;
pub use mac0::Mac0Message;
pub use recipient::{Recipient, RecipientAlgorithmClass};
pub use sign::{SignMessage, Signature};
pub use sign1::Sign1Message;

/// The CBOR value type used for header, key and claim values.
///
/// Re-exported from [`cbor2`].
pub use cbor2::Value;