matter_cert/lib.rs
1//! Matter protocol certificate format — parsing and serialisation.
2//!
3//! Implements Matter Core Specification §6.5: a TLV-encoded variant of
4//! X.509 used for both attestation chains (DAC → PAI → PAA) and
5//! operational chains (NOC → ICAC → RCAC).
6//!
7//! # Scope
8//!
9//! - **Parse and serialise** — [`MatterCertificate`] over the Matter TLV
10//! form, byte-exact on round-trip. Distinguished names including the
11//! Matter-specific OIDs ([`name`]) and the extension set
12//! ([`extensions`]: basic constraints, key usage, extended key usage,
13//! subject and authority key identifiers).
14//! - **Public keys and signatures** — P-256 key extraction
15//! ([`public_key`]) and the raw `r || s` Matter [`signature`] form.
16//! - **X.509 DER conversion** — real Matter signatures are made over the
17//! X.509 DER `TBSCertificate`, not over the TLV form, so
18//! [`MatterCertificate::verify_signed_by`] reconstructs it. Byte parity
19//! against matter.js's `asUnsignedDer()` is the correctness gate.
20//! - **Chain validation** — [`CertificateChain::validate`] against
21//! [`TrustedRoots`], checking time bounds, the CA bit above the leaf,
22//! DN linkage, the path-length constraint, and each signature.
23//! - **Issuance** — [`Builder`] constructs an [`UnsignedCertificate`], and
24//! [`operational`] adds role-aware constructors that bake in the
25//! extension and DN profile the spec mandates for RCAC, ICAC, and NOC.
26//! Signing is a separate step, so it can happen in an HSM, an OS
27//! keychain, or an offline ceremony rather than in this process.
28//!
29//! Cryptographic verification is delegated to `ring`. This crate
30//! never implements the underlying maths.
31
32#![forbid(unsafe_code)]
33
34mod tlv_tags;
35mod x509;
36
37pub mod builder;
38pub mod certificate;
39pub mod chain;
40pub mod error;
41pub mod extensions;
42pub mod name;
43pub mod operational;
44pub mod public_key;
45pub mod signature;
46#[cfg(feature = "test-support")]
47pub mod test_support;
48pub mod time;
49
50pub use builder::{Builder, UnsignedCertificate};
51pub use certificate::MatterCertificate;
52pub use chain::{CertificateChain, TrustAnchor, TrustedRoots};
53pub use error::{Error, Result};
54pub use extensions::{BasicConstraints, Extensions, ExtensionsBuilder, KeyIdentifier, KeyUsage};
55pub use name::{DistinguishedName, DnAttribute, DnAttributeValue};
56pub use public_key::PublicKey;
57pub use signature::Signature;
58pub use time::MatterTime;
59
60/// Compile-checks the Rust examples in this crate's `README.md`.
61///
62/// `#[cfg(doctest)]` means the item exists only while rustdoc is collecting
63/// doctests, so the README is compiled by `cargo test --doc` without being
64/// duplicated into the rendered crate docs.
65#[cfg(doctest)]
66#[doc = include_str!("../README.md")]
67struct ReadmeDoctests;