pub mod chain;
pub mod der;
pub mod dn;
use heapless::Vec;
pub use chain::{VerifiedIdentity, verify_chain, verify_self_signed};
pub use dn::{DistinguishedName, DnAttribute, DnAttributeKind, DnValue, MAX_NOC_CATS, MAX_RDNS};
use crate::crypto::{PUBLIC_KEY_SIZE_BYTES, PublicKey, SIGNATURE_LEN_BYTES, Signature};
use crate::error::{Error, ErrorCode, Result};
use crate::msg::{FabricId, NodeId};
use crate::tlv::{Tag, TlvReader, TlvWriter, Value};
pub const CERT_TLV_MAX: usize = 400;
pub const CERT_DER_MAX: usize = 600;
pub const SERIAL_MAX: usize = 20;
pub const KEY_ID_LEN: usize = 20;
#[must_use]
pub const fn positive_serial(mut bytes: [u8; SERIAL_MAX]) -> [u8; SERIAL_MAX] {
bytes[0] &= 0x7F;
if bytes[0] == 0x00 {
bytes[0] = 0x01;
}
bytes
}
pub const MAX_EXTENSIONS: usize = 8;
pub const MAX_KEY_PURPOSES: usize = 6;
pub const NOT_AFTER_NEVER: u32 = 0;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum SignatureAlgorithm {
EcdsaWithSha256 = 1,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum PublicKeyAlgorithm {
EcPubKey = 1,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
pub enum EllipticCurveId {
Prime256V1 = 1,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
#[non_exhaustive]
pub enum KeyPurposeId {
ServerAuth = 1,
ClientAuth = 2,
CodeSigning = 3,
EmailProtection = 4,
TimeStamping = 5,
OcspSigning = 6,
}
impl KeyPurposeId {
#[must_use]
pub const fn from_value(value: u64) -> Option<Self> {
Some(match value {
1 => Self::ServerAuth,
2 => Self::ClientAuth,
3 => Self::CodeSigning,
4 => Self::EmailProtection,
5 => Self::TimeStamping,
6 => Self::OcspSigning,
_ => return None,
})
}
}
bitflags::bitflags! {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct KeyUsage: u16 {
const DIGITAL_SIGNATURE = 0x0001;
const NON_REPUDIATION = 0x0002;
const KEY_ENCIPHERMENT = 0x0004;
const DATA_ENCIPHERMENT = 0x0008;
const KEY_AGREEMENT = 0x0010;
const KEY_CERT_SIGN = 0x0020;
const CRL_SIGN = 0x0040;
const ENCIPHER_ONLY = 0x0080;
const DECIPHER_ONLY = 0x0100;
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BasicConstraints {
pub is_ca: bool,
pub path_len_constraint: Option<u8>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Extension<'a> {
BasicConstraints(BasicConstraints),
KeyUsage(KeyUsage),
ExtendedKeyUsage(Vec<KeyPurposeId, MAX_KEY_PURPOSES>),
SubjectKeyId([u8; KEY_ID_LEN]),
AuthorityKeyId([u8; KEY_ID_LEN]),
Future(&'a [u8]),
}
impl Extension<'_> {
#[must_use]
pub const fn tag(&self) -> u8 {
match self {
Self::BasicConstraints(_) => TAG_BASIC_CONSTRAINTS,
Self::KeyUsage(_) => TAG_KEY_USAGE,
Self::ExtendedKeyUsage(_) => TAG_EXTENDED_KEY_USAGE,
Self::SubjectKeyId(_) => TAG_SUBJECT_KEY_ID,
Self::AuthorityKeyId(_) => TAG_AUTHORITY_KEY_ID,
Self::Future(_) => TAG_FUTURE_EXTENSION,
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Extensions<'a> {
entries: Vec<Extension<'a>, MAX_EXTENSIONS>,
}
impl<'a> Extensions<'a> {
#[must_use]
pub const fn new() -> Self {
Self {
entries: Vec::new(),
}
}
pub fn push(&mut self, extension: Extension<'a>) -> Result<()> {
let tag = extension.tag();
if tag != TAG_FUTURE_EXTENSION && self.entries.iter().any(|e| e.tag() == tag) {
return Err(invalid());
}
self.entries.push(extension).map_err(|_| invalid())
}
#[must_use]
pub fn entries(&self) -> &[Extension<'a>] {
&self.entries
}
#[must_use]
pub fn basic_constraints(&self) -> Option<BasicConstraints> {
self.entries.iter().find_map(|e| match e {
Extension::BasicConstraints(v) => Some(*v),
_ => None,
})
}
#[must_use]
pub fn key_usage(&self) -> Option<KeyUsage> {
self.entries.iter().find_map(|e| match e {
Extension::KeyUsage(v) => Some(*v),
_ => None,
})
}
#[must_use]
pub fn extended_key_usage(&self) -> Option<&[KeyPurposeId]> {
self.entries.iter().find_map(|e| match e {
Extension::ExtendedKeyUsage(v) => Some(v.as_slice()),
_ => None,
})
}
#[must_use]
pub fn subject_key_id(&self) -> Option<[u8; KEY_ID_LEN]> {
self.entries.iter().find_map(|e| match e {
Extension::SubjectKeyId(v) => Some(*v),
_ => None,
})
}
#[must_use]
pub fn authority_key_id(&self) -> Option<[u8; KEY_ID_LEN]> {
self.entries.iter().find_map(|e| match e {
Extension::AuthorityKeyId(v) => Some(*v),
_ => None,
})
}
pub fn future(&self) -> impl Iterator<Item = &'a [u8]> + '_ {
self.entries.iter().filter_map(|e| match e {
Extension::Future(bytes) => Some(*bytes),
_ => None,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum CertType {
Noc,
Icac,
Rcac,
Vvsc,
FirmwareSigning,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MatterCertificate<'a> {
pub serial_number: &'a [u8],
pub signature_algorithm: SignatureAlgorithm,
pub issuer: DistinguishedName<'a>,
pub not_before: u32,
pub not_after: u32,
pub subject: DistinguishedName<'a>,
pub public_key_algorithm: PublicKeyAlgorithm,
pub elliptic_curve_id: EllipticCurveId,
pub public_key: PublicKey,
pub extensions: Extensions<'a>,
pub signature: Signature,
}
const TAG_SERIAL_NUM: u8 = 1;
const TAG_SIG_ALGO: u8 = 2;
const TAG_ISSUER: u8 = 3;
const TAG_NOT_BEFORE: u8 = 4;
const TAG_NOT_AFTER: u8 = 5;
const TAG_SUBJECT: u8 = 6;
const TAG_PUB_KEY_ALGO: u8 = 7;
const TAG_EC_CURVE_ID: u8 = 8;
const TAG_EC_PUB_KEY: u8 = 9;
const TAG_EXTENSIONS: u8 = 10;
const TAG_SIGNATURE: u8 = 11;
const TAG_BASIC_CONSTRAINTS: u8 = 1;
const TAG_KEY_USAGE: u8 = 2;
const TAG_EXTENDED_KEY_USAGE: u8 = 3;
const TAG_SUBJECT_KEY_ID: u8 = 4;
const TAG_AUTHORITY_KEY_ID: u8 = 5;
const TAG_FUTURE_EXTENSION: u8 = 6;
const TAG_IS_CA: u8 = 1;
const TAG_PATH_LEN_CONSTRAINT: u8 = 2;
fn invalid() -> Error {
Error::new(ErrorCode::CertInvalid)
}
impl<'a> MatterCertificate<'a> {
pub fn decode(buf: &'a [u8]) -> Result<Self> {
if buf.len() > CERT_TLV_MAX {
return Err(invalid());
}
let mut reader = TlvReader::new(buf);
let Some(head) = reader.next_element()? else {
return Err(invalid());
};
if head.value.container() != Some(crate::tlv::ContainerKind::Structure)
|| !head.tag.is_anonymous()
{
return Err(invalid());
}
let mut serial_number = None;
let mut signature_algorithm = None;
let mut issuer = None;
let mut not_before = None;
let mut not_after = None;
let mut subject = None;
let mut public_key_algorithm = None;
let mut elliptic_curve_id = None;
let mut public_key = None;
let mut extensions = None;
let mut signature = None;
let mut previous_tag = 0u8;
loop {
let Some(element) = reader.next_element()? else {
return Err(invalid());
};
if element.value == Value::EndOfContainer {
break;
}
let Some(tag) = element.tag.context() else {
return Err(invalid());
};
if tag <= previous_tag {
return Err(invalid());
}
previous_tag = tag;
match tag {
TAG_SERIAL_NUM => {
let octets = element.octets()?;
if octets.len() > SERIAL_MAX {
return Err(invalid());
}
serial_number = Some(octets);
}
TAG_SIG_ALGO => {
signature_algorithm = Some(match element.unsigned()? {
1 => SignatureAlgorithm::EcdsaWithSha256,
_ => return Err(invalid()),
});
}
TAG_ISSUER => {
expect_list(&element)?;
issuer = Some(DistinguishedName::decode(&mut reader)?);
}
TAG_NOT_BEFORE => not_before = Some(u32_of(&element)?),
TAG_NOT_AFTER => not_after = Some(u32_of(&element)?),
TAG_SUBJECT => {
expect_list(&element)?;
subject = Some(DistinguishedName::decode(&mut reader)?);
}
TAG_PUB_KEY_ALGO => {
public_key_algorithm = Some(match element.unsigned()? {
1 => PublicKeyAlgorithm::EcPubKey,
_ => return Err(invalid()),
});
}
TAG_EC_CURVE_ID => {
elliptic_curve_id = Some(match element.unsigned()? {
1 => EllipticCurveId::Prime256V1,
_ => return Err(invalid()),
});
}
TAG_EC_PUB_KEY => {
let octets = element.octets()?;
if octets.len() != PUBLIC_KEY_SIZE_BYTES {
return Err(invalid());
}
public_key = Some(PublicKey::from_slice(octets)?);
}
TAG_EXTENSIONS => {
expect_list(&element)?;
extensions = Some(decode_extensions(&mut reader)?);
}
TAG_SIGNATURE => {
let octets = element.octets()?;
if octets.len() != SIGNATURE_LEN_BYTES {
return Err(invalid());
}
signature = Some(Signature::from_slice(octets)?);
}
_ => return Err(invalid()),
}
}
reader.finish()?;
Ok(Self {
serial_number: serial_number.ok_or_else(invalid)?,
signature_algorithm: signature_algorithm.ok_or_else(invalid)?,
issuer: issuer.ok_or_else(invalid)?,
not_before: not_before.ok_or_else(invalid)?,
not_after: not_after.ok_or_else(invalid)?,
subject: subject.ok_or_else(invalid)?,
public_key_algorithm: public_key_algorithm.ok_or_else(invalid)?,
elliptic_curve_id: elliptic_curve_id.ok_or_else(invalid)?,
public_key: public_key.ok_or_else(invalid)?,
extensions: extensions.ok_or_else(invalid)?,
signature: signature.ok_or_else(invalid)?,
})
}
pub fn encode<'b>(&self, buf: &'b mut [u8]) -> Result<&'b [u8]> {
let mut writer = TlvWriter::new(buf);
writer.start_structure(Tag::Anonymous)?;
writer.octets(Tag::Context(TAG_SERIAL_NUM), self.serial_number)?;
writer.unsigned(
Tag::Context(TAG_SIG_ALGO),
self.signature_algorithm as u8 as u64,
)?;
self.issuer.encode(&mut writer, Tag::Context(TAG_ISSUER))?;
writer.unsigned(Tag::Context(TAG_NOT_BEFORE), u64::from(self.not_before))?;
writer.unsigned(Tag::Context(TAG_NOT_AFTER), u64::from(self.not_after))?;
self.subject
.encode(&mut writer, Tag::Context(TAG_SUBJECT))?;
writer.unsigned(
Tag::Context(TAG_PUB_KEY_ALGO),
self.public_key_algorithm as u8 as u64,
)?;
writer.unsigned(
Tag::Context(TAG_EC_CURVE_ID),
self.elliptic_curve_id as u8 as u64,
)?;
writer.octets(Tag::Context(TAG_EC_PUB_KEY), self.public_key.as_bytes())?;
encode_extensions(&self.extensions, &mut writer)?;
writer.octets(Tag::Context(TAG_SIGNATURE), self.signature.as_bytes())?;
writer.end_container()?;
let written = writer.finish()?;
if written.len() > CERT_TLV_MAX {
return Err(invalid());
}
Ok(written)
}
#[must_use]
pub fn cert_type(&self) -> Option<CertType> {
use DnAttributeKind as K;
let candidates = [
(K::MatterNodeId, CertType::Noc),
(K::MatterIcacId, CertType::Icac),
(K::MatterRcacId, CertType::Rcac),
(K::MatterVvsId, CertType::Vvsc),
(K::MatterFirmwareSigningId, CertType::FirmwareSigning),
];
let mut found = None;
for (kind, cert_type) in candidates {
match self.subject.count(kind) {
0 => {}
1 if found.is_none() => found = Some(cert_type),
_ => return None,
}
}
found
}
#[must_use]
pub fn node_id(&self) -> Option<NodeId> {
self.subject.node_id()
}
#[must_use]
pub fn fabric_id(&self) -> Option<FabricId> {
self.subject.fabric_id()
}
#[must_use]
pub fn is_ca(&self) -> bool {
self.extensions
.basic_constraints()
.is_some_and(|bc| bc.is_ca)
}
#[must_use]
pub const fn is_valid_at(&self, at: u32) -> bool {
at >= self.not_before && (self.not_after == NOT_AFTER_NEVER || at <= self.not_after)
}
pub fn validate(&self) -> Result<()> {
let Some(cert_type) = self.cert_type() else {
return Err(invalid());
};
self.validate_as(cert_type)
}
pub fn validate_as(&self, cert_type: CertType) -> Result<()> {
if self.cert_type() != Some(cert_type) {
return Err(invalid());
}
self.validate_subject_dn(cert_type)?;
self.validate_extensions(cert_type)
}
fn validate_subject_dn(&self, cert_type: CertType) -> Result<()> {
use DnAttributeKind as K;
let dn = &self.subject;
if dn.is_empty() || self.issuer.is_empty() {
return Err(invalid());
}
let forbidden: &[K] = match cert_type {
CertType::Noc => &[K::MatterIcacId, K::MatterRcacId, K::MatterVvsId],
CertType::Icac => &[
K::MatterNodeId,
K::MatterRcacId,
K::MatterNocCat,
K::MatterVvsId,
],
CertType::Rcac => &[
K::MatterNodeId,
K::MatterIcacId,
K::MatterNocCat,
K::MatterVvsId,
],
CertType::Vvsc => &[K::MatterNodeId, K::MatterFabricId, K::MatterNocCat],
CertType::FirmwareSigning => &[],
};
for kind in forbidden {
if dn.count(*kind) != 0 {
return Err(invalid());
}
}
match cert_type {
CertType::Noc => {
let Some(node_id) = dn.node_id() else {
return Err(invalid());
};
if !node_id.is_operational() {
return Err(invalid());
}
let Some(fabric_id) = dn.fabric_id() else {
return Err(invalid());
};
if fabric_id.0 == 0 {
return Err(invalid());
}
validate_noc_cats(dn)?;
}
CertType::Icac | CertType::Rcac => {
match dn.count(K::MatterFabricId) {
0 => {}
1 => {
if dn.fabric_id().is_none_or(|f| f.0 == 0) {
return Err(invalid());
}
}
_ => return Err(invalid()),
}
}
CertType::Vvsc | CertType::FirmwareSigning => {}
}
Ok(())
}
fn validate_extensions(&self, cert_type: CertType) -> Result<()> {
let ext = &self.extensions;
let (Some(subject_key_id), Some(authority_key_id)) =
(ext.subject_key_id(), ext.authority_key_id())
else {
return Err(invalid());
};
let Some(basic) = ext.basic_constraints() else {
return Err(invalid());
};
if !basic.is_ca && basic.path_len_constraint.is_some() {
return Err(invalid());
}
let Some(key_usage) = ext.key_usage() else {
return Err(invalid());
};
let expected_eku: Option<&[KeyPurposeId]> = match cert_type {
CertType::Noc => Some(&[KeyPurposeId::ServerAuth, KeyPurposeId::ClientAuth]),
CertType::FirmwareSigning => Some(&[KeyPurposeId::CodeSigning]),
CertType::Icac | CertType::Rcac => Some(&[]),
CertType::Vvsc => None,
};
match cert_type {
CertType::Noc | CertType::Vvsc | CertType::FirmwareSigning => {
if basic.is_ca {
return Err(invalid());
}
if key_usage != KeyUsage::DIGITAL_SIGNATURE {
return Err(invalid());
}
}
CertType::Icac | CertType::Rcac => {
if !basic.is_ca {
return Err(invalid());
}
let required = KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN;
let permitted = required | KeyUsage::DIGITAL_SIGNATURE;
if !key_usage.contains(required) || !permitted.contains(key_usage) {
return Err(invalid());
}
if cert_type == CertType::Rcac && authority_key_id != subject_key_id {
return Err(invalid());
}
}
}
if let Some(expected) = expected_eku {
match (expected.is_empty(), ext.extended_key_usage()) {
(true, None) => {}
(true, Some(_)) => return Err(invalid()),
(false, None) => return Err(invalid()),
(false, Some(present)) => {
if present.len() != expected.len()
|| !expected.iter().all(|p| present.contains(p))
{
return Err(invalid());
}
}
}
}
Ok(())
}
}
fn validate_noc_cats(dn: &DistinguishedName<'_>) -> Result<()> {
if dn.count(DnAttributeKind::MatterNocCat) > MAX_NOC_CATS {
return Err(invalid());
}
let cats = dn.noc_cats();
for (index, cat) in cats.iter().enumerate() {
if !cat.is_valid() {
return Err(invalid());
}
if cats.get(index.saturating_add(1)..).is_some_and(|rest| {
rest.iter()
.any(|other| other.identifier() == cat.identifier())
}) {
return Err(invalid());
}
}
Ok(())
}
fn expect_list(element: &crate::tlv::Element<'_>) -> Result<()> {
if element.value.container() == Some(crate::tlv::ContainerKind::List) {
Ok(())
} else {
Err(invalid())
}
}
fn u32_of(element: &crate::tlv::Element<'_>) -> Result<u32> {
u32::try_from(element.unsigned()?).map_err(|_| invalid())
}
fn decode_extensions<'a>(reader: &mut TlvReader<'a>) -> Result<Extensions<'a>> {
let mut out = Extensions::new();
loop {
let Some(element) = reader.next_element()? else {
return Err(invalid());
};
if element.value == Value::EndOfContainer {
break;
}
let Some(tag) = element.tag.context() else {
return Err(invalid());
};
let extension = match tag {
TAG_BASIC_CONSTRAINTS => {
if element.value.container() != Some(crate::tlv::ContainerKind::Structure) {
return Err(invalid());
}
Extension::BasicConstraints(decode_basic_constraints(reader)?)
}
TAG_KEY_USAGE => {
let raw = u16::try_from(element.unsigned()?).map_err(|_| invalid())?;
Extension::KeyUsage(KeyUsage::from_bits(raw).ok_or_else(invalid)?)
}
TAG_EXTENDED_KEY_USAGE => {
if element.value.container() != Some(crate::tlv::ContainerKind::Array) {
return Err(invalid());
}
Extension::ExtendedKeyUsage(decode_key_purposes(reader)?)
}
TAG_SUBJECT_KEY_ID => Extension::SubjectKeyId(key_id(&element)?),
TAG_AUTHORITY_KEY_ID => Extension::AuthorityKeyId(key_id(&element)?),
TAG_FUTURE_EXTENSION => Extension::Future(element.octets()?),
_ => return Err(invalid()),
};
out.push(extension)?;
}
Ok(out)
}
fn key_id(element: &crate::tlv::Element<'_>) -> Result<[u8; KEY_ID_LEN]> {
<[u8; KEY_ID_LEN]>::try_from(element.octets()?).map_err(|_| invalid())
}
fn decode_basic_constraints(reader: &mut TlvReader<'_>) -> Result<BasicConstraints> {
let mut is_ca = None;
let mut path_len_constraint = None;
let mut previous_tag = 0u8;
loop {
let Some(element) = reader.next_element()? else {
return Err(invalid());
};
if element.value == Value::EndOfContainer {
break;
}
let Some(tag) = element.tag.context() else {
return Err(invalid());
};
if tag <= previous_tag {
return Err(invalid());
}
previous_tag = tag;
match tag {
TAG_IS_CA => is_ca = Some(element.bool()?),
TAG_PATH_LEN_CONSTRAINT => {
path_len_constraint =
Some(u8::try_from(element.unsigned()?).map_err(|_| invalid())?);
}
_ => return Err(invalid()),
}
}
Ok(BasicConstraints {
is_ca: is_ca.ok_or_else(invalid)?,
path_len_constraint,
})
}
fn decode_key_purposes(reader: &mut TlvReader<'_>) -> Result<Vec<KeyPurposeId, MAX_KEY_PURPOSES>> {
let mut out = Vec::new();
loop {
let Some(element) = reader.next_element()? else {
return Err(invalid());
};
if element.value == Value::EndOfContainer {
break;
}
if !element.tag.is_anonymous() {
return Err(invalid());
}
let purpose = KeyPurposeId::from_value(element.unsigned()?).ok_or_else(invalid)?;
out.push(purpose).map_err(|_| invalid())?;
}
if out.is_empty() {
return Err(invalid());
}
Ok(out)
}
fn encode_extensions(extensions: &Extensions<'_>, writer: &mut TlvWriter<'_>) -> Result<()> {
writer.start_list(Tag::Context(TAG_EXTENSIONS))?;
for extension in extensions.entries() {
let tag = Tag::Context(extension.tag());
match extension {
Extension::BasicConstraints(basic) => {
writer.start_structure(tag)?;
writer.bool(Tag::Context(TAG_IS_CA), basic.is_ca)?;
if let Some(path_len) = basic.path_len_constraint {
writer.unsigned(Tag::Context(TAG_PATH_LEN_CONSTRAINT), u64::from(path_len))?;
}
writer.end_container()?;
}
Extension::KeyUsage(key_usage) => {
writer.unsigned(tag, u64::from(key_usage.bits()))?;
}
Extension::ExtendedKeyUsage(purposes) => {
writer.start_array(tag)?;
for purpose in purposes {
writer.unsigned(Tag::Anonymous, *purpose as u8 as u64)?;
}
writer.end_container()?;
}
Extension::SubjectKeyId(id) | Extension::AuthorityKeyId(id) => {
writer.octets(tag, id)?;
}
Extension::Future(bytes) => writer.octets(tag, bytes)?,
}
}
writer.end_container()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::msg::CaseAuthenticatedTag;
const KEY_A: [u8; KEY_ID_LEN] = [0xAA; KEY_ID_LEN];
const KEY_B: [u8; KEY_ID_LEN] = [0xBB; KEY_ID_LEN];
fn a_public_key() -> PublicKey {
let mut bytes = [0x11u8; PUBLIC_KEY_SIZE_BYTES];
bytes[0] = 0x04;
PublicKey::from_bytes(bytes)
}
fn extensions(entries: &[Extension<'static>]) -> Extensions<'static> {
let mut out = Extensions::new();
for entry in entries {
out.push(entry.clone()).expect("fits");
}
out
}
fn cert(cert_type: CertType) -> MatterCertificate<'static> {
let mut subject = DistinguishedName::new();
let mut ext = heapless::Vec::<Extension<'static>, MAX_EXTENSIONS>::new();
let is_ca = matches!(cert_type, CertType::Icac | CertType::Rcac);
match cert_type {
CertType::Noc => {
subject.push(DnAttribute::node_id(NodeId(1))).expect("push");
subject
.push(DnAttribute::fabric_id(FabricId(0xFAB0_0000_0000_001D)))
.expect("push");
}
CertType::Icac => subject
.push(DnAttribute::uint(DnAttributeKind::MatterIcacId, 3))
.expect("push"),
CertType::Rcac => subject
.push(DnAttribute::uint(DnAttributeKind::MatterRcacId, 1))
.expect("push"),
CertType::Vvsc => subject
.push(DnAttribute::uint(DnAttributeKind::MatterVvsId, 7))
.expect("push"),
CertType::FirmwareSigning => subject
.push(DnAttribute::uint(
DnAttributeKind::MatterFirmwareSigningId,
9,
))
.expect("push"),
}
ext.push(Extension::BasicConstraints(BasicConstraints {
is_ca,
path_len_constraint: None,
}))
.expect("fits");
ext.push(Extension::KeyUsage(if is_ca {
KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN
} else {
KeyUsage::DIGITAL_SIGNATURE
}))
.expect("fits");
match cert_type {
CertType::Noc => {
let mut purposes = Vec::new();
purposes.push(KeyPurposeId::ServerAuth).expect("fits");
purposes.push(KeyPurposeId::ClientAuth).expect("fits");
ext.push(Extension::ExtendedKeyUsage(purposes))
.expect("fits");
}
CertType::FirmwareSigning => {
let mut purposes = Vec::new();
purposes.push(KeyPurposeId::CodeSigning).expect("fits");
ext.push(Extension::ExtendedKeyUsage(purposes))
.expect("fits");
}
_ => {}
}
ext.push(Extension::SubjectKeyId(KEY_A)).expect("fits");
ext.push(Extension::AuthorityKeyId(if cert_type == CertType::Rcac {
KEY_A
} else {
KEY_B
}))
.expect("fits");
let mut issuer = DistinguishedName::new();
issuer
.push(DnAttribute::uint(DnAttributeKind::MatterRcacId, 1))
.expect("push");
MatterCertificate {
serial_number: &[0x01, 0x02],
signature_algorithm: SignatureAlgorithm::EcdsaWithSha256,
issuer,
not_before: 100,
not_after: 200,
subject,
public_key_algorithm: PublicKeyAlgorithm::EcPubKey,
elliptic_curve_id: EllipticCurveId::Prime256V1,
public_key: a_public_key(),
extensions: extensions(&ext),
signature: Signature::from_bytes([0x22; SIGNATURE_LEN_BYTES]),
}
}
#[test]
fn the_built_certificates_are_valid_to_begin_with() {
for cert_type in [
CertType::Noc,
CertType::Icac,
CertType::Rcac,
CertType::Vvsc,
CertType::FirmwareSigning,
] {
let c = cert(cert_type);
assert_eq!(c.cert_type(), Some(cert_type), "{cert_type:?}");
c.validate()
.unwrap_or_else(|e| panic!("{cert_type:?}: {e}"));
}
}
#[test]
fn a_noc_with_fabric_id_zero_is_refused() {
let mut c = cert(CertType::Noc);
c.subject = DistinguishedName::new();
c.subject
.push(DnAttribute::node_id(NodeId(1)))
.expect("push");
c.subject
.push(DnAttribute::fabric_id(FabricId(0)))
.expect("push");
assert!(c.validate().is_err());
}
#[test]
fn a_noc_without_a_fabric_id_is_refused() {
let mut c = cert(CertType::Noc);
c.subject = DistinguishedName::new();
c.subject
.push(DnAttribute::node_id(NodeId(1)))
.expect("push");
assert!(c.validate().is_err());
}
#[test]
fn a_noc_whose_node_id_is_not_operational_is_refused() {
let mut c = cert(CertType::Noc);
c.subject = DistinguishedName::new();
c.subject
.push(DnAttribute::node_id(NodeId(0xFFFF_FFFF_FFFF_0001)))
.expect("push");
c.subject
.push(DnAttribute::fabric_id(FabricId(1)))
.expect("push");
assert!(c.validate().is_err());
}
#[test]
fn a_subject_that_claims_two_certificate_types_has_no_type() {
let mut c = cert(CertType::Noc);
c.subject
.push(DnAttribute::uint(DnAttributeKind::MatterRcacId, 1))
.expect("push");
assert_eq!(c.cert_type(), None);
assert!(c.validate().is_err());
}
#[test]
fn a_ca_certificate_must_say_it_is_one() {
for cert_type in [CertType::Icac, CertType::Rcac] {
let mut c = cert(cert_type);
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: false,
path_len_constraint: None,
}),
Extension::KeyUsage(KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_A),
]);
assert!(c.validate().is_err(), "{cert_type:?}");
}
}
#[test]
fn a_leaf_certificate_must_not_claim_to_be_a_ca() {
let mut c = cert(CertType::Noc);
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: true,
path_len_constraint: None,
}),
Extension::KeyUsage(KeyUsage::DIGITAL_SIGNATURE),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert!(c.validate().is_err());
}
#[test]
fn a_path_len_constraint_needs_is_ca() {
let mut c = cert(CertType::Noc);
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: false,
path_len_constraint: Some(0),
}),
Extension::KeyUsage(KeyUsage::DIGITAL_SIGNATURE),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert!(c.validate().is_err());
}
#[test]
fn a_roots_authority_key_id_must_equal_its_subject_key_id() {
let mut c = cert(CertType::Rcac);
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: true,
path_len_constraint: None,
}),
Extension::KeyUsage(KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert!(c.validate().is_err());
cert(CertType::Icac).validate().expect("icac");
}
#[test]
fn the_key_usage_flags_a_type_allows_are_exactly_those() {
for usage in [
KeyUsage::DIGITAL_SIGNATURE | KeyUsage::KEY_AGREEMENT,
KeyUsage::KEY_CERT_SIGN,
KeyUsage::empty(),
] {
let mut c = cert(CertType::Noc);
let mut ext = Extensions::new();
ext.push(Extension::BasicConstraints(BasicConstraints {
is_ca: false,
path_len_constraint: None,
}))
.expect("fits");
ext.push(Extension::KeyUsage(usage)).expect("fits");
let mut purposes = Vec::new();
purposes.push(KeyPurposeId::ServerAuth).expect("fits");
purposes.push(KeyPurposeId::ClientAuth).expect("fits");
ext.push(Extension::ExtendedKeyUsage(purposes))
.expect("fits");
ext.push(Extension::SubjectKeyId(KEY_A)).expect("fits");
ext.push(Extension::AuthorityKeyId(KEY_B)).expect("fits");
c.extensions = ext;
assert!(c.validate().is_err(), "{usage:?}");
}
}
#[test]
fn a_ca_may_add_digital_signature_but_nothing_else() {
let base = KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN;
for (usage, ok) in [
(base, true),
(base | KeyUsage::DIGITAL_SIGNATURE, true),
(base | KeyUsage::KEY_AGREEMENT, false),
(KeyUsage::KEY_CERT_SIGN, false),
(KeyUsage::CRL_SIGN, false),
] {
let mut c = cert(CertType::Icac);
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: true,
path_len_constraint: None,
}),
Extension::KeyUsage(usage),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert_eq!(c.validate().is_ok(), ok, "{usage:?}");
}
}
#[test]
fn a_ca_must_not_carry_an_extended_key_usage() {
let mut c = cert(CertType::Icac);
let mut purposes = Vec::new();
purposes.push(KeyPurposeId::ServerAuth).expect("fits");
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: true,
path_len_constraint: None,
}),
Extension::KeyUsage(KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN),
Extension::ExtendedKeyUsage(purposes),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert!(c.validate().is_err());
}
#[test]
fn a_nocs_extended_key_usage_is_both_purposes_in_either_order() {
for (purposes, ok) in [
(
&[KeyPurposeId::ServerAuth, KeyPurposeId::ClientAuth][..],
true,
),
(
&[KeyPurposeId::ClientAuth, KeyPurposeId::ServerAuth][..],
true,
),
(&[KeyPurposeId::ServerAuth][..], false),
(
&[KeyPurposeId::ServerAuth, KeyPurposeId::CodeSigning][..],
false,
),
(
&[
KeyPurposeId::ServerAuth,
KeyPurposeId::ClientAuth,
KeyPurposeId::CodeSigning,
][..],
false,
),
] {
let mut c = cert(CertType::Noc);
let mut list = Vec::new();
for p in purposes {
list.push(*p).expect("fits");
}
c.extensions = extensions(&[
Extension::BasicConstraints(BasicConstraints {
is_ca: false,
path_len_constraint: None,
}),
Extension::KeyUsage(KeyUsage::DIGITAL_SIGNATURE),
Extension::ExtendedKeyUsage(list),
Extension::SubjectKeyId(KEY_A),
Extension::AuthorityKeyId(KEY_B),
]);
assert_eq!(c.validate().is_ok(), ok, "{purposes:?}");
}
}
#[test]
fn a_missing_key_identifier_is_refused() {
for present in [
&[Extension::SubjectKeyId(KEY_A)][..],
&[Extension::AuthorityKeyId(KEY_B)][..],
&[][..],
] {
let mut c = cert(CertType::Icac);
let mut ext = Extensions::new();
ext.push(Extension::BasicConstraints(BasicConstraints {
is_ca: true,
path_len_constraint: None,
}))
.expect("fits");
ext.push(Extension::KeyUsage(
KeyUsage::KEY_CERT_SIGN | KeyUsage::CRL_SIGN,
))
.expect("fits");
for e in present {
ext.push(e.clone()).expect("fits");
}
c.extensions = ext;
assert!(c.validate().is_err());
}
}
#[test]
fn a_duplicate_extension_is_refused_on_push() {
let mut ext = Extensions::new();
ext.push(Extension::KeyUsage(KeyUsage::DIGITAL_SIGNATURE))
.expect("first");
assert!(
ext.push(Extension::KeyUsage(KeyUsage::CRL_SIGN)).is_err(),
"a second key-usage"
);
ext.push(Extension::Future(&[1])).expect("first future");
ext.push(Extension::Future(&[2])).expect("second future");
assert_eq!(ext.future().count(), 2);
}
#[test]
fn noc_cats_must_be_versioned_and_distinct() {
let cases: &[(&[u32], bool)] = &[
(&[0xABCD_0002], true),
(&[0xABCD_0004, 0xABCE_0018, 0xABCF_0002], true),
(&[0xABCD_0000], false),
(&[0xABCD_0004, 0xABCD_0002], false),
];
for (cats, ok) in cases {
let mut c = cert(CertType::Noc);
c.subject = DistinguishedName::new();
c.subject
.push(DnAttribute::node_id(NodeId(1)))
.expect("push");
c.subject
.push(DnAttribute::fabric_id(FabricId(1)))
.expect("push");
for cat in *cats {
c.subject
.push(DnAttribute::noc_cat(CaseAuthenticatedTag(*cat)))
.expect("push");
}
assert_eq!(c.validate().is_ok(), *ok, "{cats:02x?}");
}
}
#[test]
fn a_dn_refuses_a_sixth_attribute() {
let mut dn = DistinguishedName::new();
for _ in 0..MAX_RDNS {
dn.push(DnAttribute::string(DnAttributeKind::CommonName, "x"))
.expect("fits");
}
assert!(
dn.push(DnAttribute::string(DnAttributeKind::CommonName, "x"))
.is_err()
);
}
#[test]
fn a_round_trip_survives_a_printable_string_attribute() {
let mut c = cert(CertType::Rcac);
c.subject = DistinguishedName::new();
c.subject
.push(DnAttribute::uint(DnAttributeKind::MatterRcacId, 1))
.expect("push");
c.subject
.push(DnAttribute::printable(
DnAttributeKind::CommonName,
"ROOT CA HOME 3",
))
.expect("push");
let mut buf = [0u8; CERT_TLV_MAX];
let bytes = c.encode(&mut buf).expect("encode");
assert!(
bytes.contains(&0x81),
"the printable-string tag is on the wire"
);
let mut round = [0u8; CERT_TLV_MAX];
round[..bytes.len()].copy_from_slice(bytes);
let decoded = MatterCertificate::decode(&round[..bytes.len()]).expect("decode");
let attribute = decoded.subject.attributes()[1];
assert!(attribute.printable_string);
assert_eq!(attribute.as_str(), Some("ROOT CA HOME 3"));
assert_eq!(decoded.subject, c.subject);
}
#[test]
fn the_printable_string_form_only_exists_where_table_87_defines_it() {
let mut dn = DistinguishedName::new();
assert!(
dn.push(DnAttribute::printable(
DnAttributeKind::DomainComponent,
"example"
))
.is_err()
);
assert!(
dn.push(DnAttribute {
kind: DnAttributeKind::MatterNodeId,
printable_string: true,
value: DnValue::Uint(1),
})
.is_err()
);
assert!(
dn.push(DnAttribute::uint(DnAttributeKind::CommonName, 1))
.is_err()
);
assert!(
dn.push(DnAttribute::string(DnAttributeKind::MatterNodeId, "x"))
.is_err()
);
}
#[test]
fn a_noc_cat_above_32_bits_is_refused() {
let mut dn = DistinguishedName::new();
assert!(
dn.push(DnAttribute::uint(
DnAttributeKind::MatterNocCat,
0x1_0000_0000
))
.is_err()
);
dn.push(DnAttribute::uint(
DnAttributeKind::MatterNodeId,
0x0123_4567_89AB_CDEF,
))
.expect("64 bits is fine for a node id");
}
#[test]
fn a_serial_number_longer_than_20_octets_is_refused() {
let mut c = cert(CertType::Rcac);
const LONG: [u8; SERIAL_MAX + 1] = [0x01; SERIAL_MAX + 1];
c.serial_number = &LONG;
let mut buf = [0u8; CERT_TLV_MAX];
let bytes = c.encode(&mut buf).expect("encode");
let mut round = [0u8; CERT_TLV_MAX];
round[..bytes.len()].copy_from_slice(bytes);
assert_eq!(
MatterCertificate::decode(&round[..bytes.len()])
.map(|_| ())
.unwrap_err()
.code(),
ErrorCode::CertInvalid
);
}
#[test]
fn elements_out_of_order_are_refused() {
let mut buf = [0u8; 64];
let mut writer = TlvWriter::new(&mut buf);
writer.start_structure(Tag::Anonymous).expect("start");
writer
.unsigned(Tag::Context(TAG_SIG_ALGO), 1)
.expect("sig-algo first");
writer
.octets(Tag::Context(TAG_SERIAL_NUM), &[1])
.expect("serial second");
writer.end_container().expect("end");
let bytes = writer.finish().expect("finish");
let mut round = [0u8; 64];
round[..bytes.len()].copy_from_slice(bytes);
assert!(MatterCertificate::decode(&round[..bytes.len()]).is_err());
}
#[test]
fn an_undefined_algorithm_or_curve_is_refused() {
for (tag, value) in [
(TAG_SIG_ALGO, 2u64),
(TAG_PUB_KEY_ALGO, 2),
(TAG_EC_CURVE_ID, 2),
] {
let mut buf = [0u8; 64];
let mut writer = TlvWriter::new(&mut buf);
writer.start_structure(Tag::Anonymous).expect("start");
writer.unsigned(Tag::Context(tag), value).expect("value");
writer.end_container().expect("end");
let bytes = writer.finish().expect("finish");
let mut round = [0u8; 64];
round[..bytes.len()].copy_from_slice(bytes);
assert!(
MatterCertificate::decode(&round[..bytes.len()]).is_err(),
"tag {tag} value {value}"
);
}
}
#[test]
fn undefined_key_usage_flags_are_refused() {
assert!(KeyUsage::from_bits(0x0200).is_none());
assert_eq!(KeyUsage::from_bits(0x01FF).map(|k| k.bits()), Some(0x01FF));
}
#[test]
fn a_certificate_larger_than_400_octets_is_refused() {
let oversized = [0u8; CERT_TLV_MAX + 1];
assert!(MatterCertificate::decode(&oversized).is_err());
}
#[test]
fn a_not_after_of_zero_never_expires() {
let mut c = cert(CertType::Noc);
c.not_after = NOT_AFTER_NEVER;
assert!(c.is_valid_at(u32::MAX));
assert!(!c.is_valid_at(c.not_before.saturating_sub(1)));
}
fn encodes(serial: &[u8]) -> bool {
let mut c = cert(CertType::Noc);
c.serial_number = serial;
let mut buf = [0u8; CERT_DER_MAX];
der::tbs_certificate(&c, &mut buf).is_ok()
}
#[test]
fn a_normalised_digest_always_encodes_as_a_serial_number() {
for first in 0..=u8::MAX {
for second in 0..=u8::MAX {
let mut digest = [0x5Au8; SERIAL_MAX];
digest[0] = first;
digest[1] = second;
let serial = positive_serial(digest);
assert_ne!(serial[0] & 0x80, 0x80, "a serial is a *positive* integer");
assert_ne!(serial[0], 0x00, "0x00 would be a redundant sign octet");
assert!(encodes(&serial), "digest {first:#04x}{second:#04x}");
}
}
}
#[test]
fn the_writer_refuses_a_redundant_sign_octet() {
for raw in [
[0x00, 0x01],
[0xFF, 0x80],
] {
let mut digest = [0x5Au8; SERIAL_MAX];
digest[..2].copy_from_slice(&raw);
assert!(!encodes(&digest), "{raw:02x?}");
assert!(encodes(&positive_serial(digest)), "{raw:02x?}");
}
}
}