use crate::attestation::chain::verify_dac_chain;
use crate::attestation::x509::X509Certificate;
use crate::attestation::{
ATTESTATION_NONCE_LEN, AttestationElements, CSR_NONCE_LEN, Csr, NocsrElements,
verify_attestation, verify_nocsr,
};
use crate::ca::{CertAuthority, Identity, Validity};
use crate::cert::CERT_TLV_MAX;
use crate::clusters::generated::{general_commissioning, operational_credentials};
use crate::crypto::{KeyStore, PublicKey, Signature, SymmetricKey};
use crate::error::{Error, ErrorCode, Result};
use crate::im::{ClusterId, CommandId, EndpointId};
use crate::msg::{NodeId, VendorId};
use crate::tlv::{ContainerKind, Tag, TlvWriter, ToTlv};
pub const ROOT_ENDPOINT: EndpointId = 0;
pub const AUTONOMOUS_FAIL_SAFE_SECONDS: u16 = 60;
pub const DER_CERT_MAX: usize = 600;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Stage {
ArmFailSafe,
SetRegulatoryConfig,
RequestDac,
RequestPai,
RequestAttestation,
RequestCsr,
AddTrustedRoot,
AddNoc,
Operational,
CommissioningComplete,
Done,
}
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum Step<'a> {
Invoke {
endpoint: EndpointId,
cluster: ClusterId,
command: CommandId,
fields: &'a [u8],
},
Operational {
node_id: NodeId,
},
Done,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Attestation {
Trusted,
Failed(ErrorCode),
}
#[derive(Debug, Clone, Copy)]
pub struct Plan {
pub identity: Identity,
pub case_admin_subject: u64,
pub admin_vendor_id: VendorId,
pub fail_safe_seconds: u16,
pub validity: Validity,
pub needs_regulatory_config: bool,
pub regulatory_location: general_commissioning::RegulatoryLocationTypeEnum,
}
impl Plan {
#[must_use]
pub const fn new(
identity: Identity,
case_admin_subject: u64,
admin_vendor_id: VendorId,
validity: Validity,
) -> Self {
Self {
identity,
case_admin_subject,
admin_vendor_id,
fail_safe_seconds: 900,
validity,
needs_regulatory_config: false,
regulatory_location: general_commissioning::RegulatoryLocationTypeEnum::IndoorOutdoor,
}
}
#[must_use]
pub const fn with_regulatory_config(
mut self,
location: general_commissioning::RegulatoryLocationTypeEnum,
) -> Self {
self.needs_regulatory_config = true;
self.regulatory_location = location;
self
}
#[must_use]
pub const fn with_fail_safe(mut self, seconds: u16) -> Self {
self.fail_safe_seconds = seconds;
self
}
}
#[derive(Debug)]
pub struct Commissioner {
stage: Stage,
plan: Plan,
challenge: SymmetricKey,
attestation_nonce: [u8; ATTESTATION_NONCE_LEN],
csr_nonce: [u8; CSR_NONCE_LEN],
dac: heapless::Vec<u8, DER_CERT_MAX>,
pai: heapless::Vec<u8, DER_CERT_MAX>,
operational_key: Option<PublicKey>,
attestation: Option<Attestation>,
fields: heapless::Vec<u8, 1024>,
}
impl Commissioner {
#[must_use]
pub fn new(
plan: Plan,
challenge: SymmetricKey,
attestation_nonce: [u8; ATTESTATION_NONCE_LEN],
csr_nonce: [u8; CSR_NONCE_LEN],
) -> Self {
Self {
stage: Stage::ArmFailSafe,
plan,
challenge,
attestation_nonce,
csr_nonce,
dac: heapless::Vec::new(),
pai: heapless::Vec::new(),
operational_key: None,
attestation: None,
fields: heapless::Vec::new(),
}
}
#[must_use]
pub const fn stage(&self) -> Stage {
self.stage
}
#[must_use]
pub const fn attestation(&self) -> Option<Attestation> {
self.attestation
}
#[must_use]
pub const fn operational_key(&self) -> Option<PublicKey> {
self.operational_key
}
#[must_use]
pub const fn node_id(&self) -> NodeId {
self.plan.identity.node_id
}
pub fn step(&mut self) -> Result<Step<'_>> {
use operational_credentials::command as opcreds;
match self.stage {
Stage::ArmFailSafe => {
self.encode(&general_commissioning::ArmFailSafeFields {
expiry_length_seconds: self.plan.fail_safe_seconds,
breadcrumb: 0,
})?;
Ok(self.invoke(
general_commissioning::ID,
general_commissioning::command::ARM_FAIL_SAFE,
))
}
Stage::SetRegulatoryConfig => {
self.encode(&general_commissioning::SetRegulatoryConfigFields {
new_regulatory_config: self.plan.regulatory_location,
country_code: "XX",
breadcrumb: 0,
})?;
Ok(self.invoke(
general_commissioning::ID,
general_commissioning::command::SET_REGULATORY_CONFIG,
))
}
Stage::RequestDac => {
self.encode(&operational_credentials::CertificateChainRequestFields {
certificate_type:
operational_credentials::CertificateChainTypeEnum::DACCertificate,
})?;
Ok(self.invoke(
operational_credentials::ID,
opcreds::CERTIFICATE_CHAIN_REQUEST,
))
}
Stage::RequestPai => {
self.encode(&operational_credentials::CertificateChainRequestFields {
certificate_type:
operational_credentials::CertificateChainTypeEnum::PAICertificate,
})?;
Ok(self.invoke(
operational_credentials::ID,
opcreds::CERTIFICATE_CHAIN_REQUEST,
))
}
Stage::RequestAttestation => {
let nonce = self.attestation_nonce;
self.encode(&operational_credentials::AttestationRequestFields {
attestation_nonce: &nonce,
})?;
Ok(self.invoke(operational_credentials::ID, opcreds::ATTESTATION_REQUEST))
}
Stage::RequestCsr => {
let nonce = self.csr_nonce;
self.encode(&operational_credentials::CSRRequestFields {
csr_nonce: &nonce,
is_for_update_noc: Some(false),
})?;
Ok(self.invoke(operational_credentials::ID, opcreds::CSR_REQUEST))
}
Stage::AddTrustedRoot | Stage::AddNoc => {
Err(Error::new(ErrorCode::InvalidState))
}
Stage::Operational => Ok(Step::Operational {
node_id: self.plan.identity.node_id,
}),
Stage::CommissioningComplete => {
self.fields.clear();
Ok(self.invoke(
general_commissioning::ID,
general_commissioning::command::COMMISSIONING_COMPLETE,
))
}
Stage::Done => Ok(Step::Done),
}
}
pub fn add_root<K: KeyStore>(&mut self, ca: &CertAuthority, keys: &K) -> Result<Step<'_>> {
if self.stage != Stage::AddTrustedRoot {
return Err(Error::new(ErrorCode::InvalidState));
}
let mut root = [0u8; CERT_TLV_MAX];
let root = ca.self_signed_root(keys, &mut root, self.plan.validity)?;
self.encode(&operational_credentials::AddTrustedRootCertificateFields {
root_ca_certificate: root,
})?;
Ok(self.invoke(
operational_credentials::ID,
operational_credentials::command::ADD_TRUSTED_ROOT_CERTIFICATE,
))
}
pub fn add_noc<K: KeyStore>(
&mut self,
ca: &CertAuthority,
keys: &K,
icac: Option<&[u8]>,
) -> Result<Step<'_>> {
if self.stage != Stage::AddNoc {
return Err(Error::new(ErrorCode::InvalidState));
}
let public_key = self
.operational_key
.ok_or_else(|| Error::new(ErrorCode::InvalidState))?;
let mut noc = [0u8; CERT_TLV_MAX];
let noc = ca.issue_noc(
keys,
&mut noc,
&self.plan.identity,
&public_key,
self.plan.validity,
)?;
let ipk = self.ipk(ca, keys)?;
self.encode(&operational_credentials::AddNOCFields {
noc_value: noc,
icac_value: icac,
ipk_value: &ipk,
case_admin_subject: self.plan.case_admin_subject,
admin_vendor_id: self.plan.admin_vendor_id,
})?;
Ok(self.invoke(
operational_credentials::ID,
operational_credentials::command::ADD_NOC,
))
}
fn ipk<K: KeyStore>(&self, ca: &CertAuthority, keys: &K) -> Result<[u8; 16]> {
let mut material = [0u8; 8];
material.copy_from_slice(&self.plan.identity.fabric_id.0.to_be_bytes());
let signature = keys.sign(ca.key(), &material)?;
let digest = crate::crypto::hash(signature.as_bytes());
let mut ipk = [0u8; 16];
let head = digest
.get(..16)
.ok_or_else(|| Error::new(ErrorCode::InvalidState))?;
ipk.copy_from_slice(head);
Ok(ipk)
}
pub fn on_response(&mut self, fields: Option<&[u8]>) -> Result<()> {
match self.stage {
Stage::ArmFailSafe => {
self.check_commissioning_error(fields)?;
self.stage = if self.plan.needs_regulatory_config {
Stage::SetRegulatoryConfig
} else {
Stage::RequestDac
};
}
Stage::SetRegulatoryConfig => {
self.check_commissioning_error(fields)?;
self.stage = Stage::RequestDac;
}
Stage::RequestDac => {
let certificate = Self::certificate(fields)?;
self.dac = heapless::Vec::from_slice(certificate)
.map_err(|_| Error::new(ErrorCode::BufferTooSmall))?;
self.stage = Stage::RequestPai;
}
Stage::RequestPai => {
let certificate = Self::certificate(fields)?;
self.pai = heapless::Vec::from_slice(certificate)
.map_err(|_| Error::new(ErrorCode::BufferTooSmall))?;
self.stage = Stage::RequestAttestation;
}
Stage::RequestAttestation => {
self.check_attestation(fields)?;
self.stage = Stage::RequestCsr;
}
Stage::RequestCsr => {
self.check_csr(fields)?;
self.stage = Stage::AddTrustedRoot;
}
Stage::AddTrustedRoot => {
if fields.is_some_and(|fields| !fields.is_empty()) {
return Err(Error::new(ErrorCode::InvalidState));
}
self.stage = Stage::AddNoc;
}
Stage::AddNoc => {
Self::check_noc_status(fields)?;
self.stage = Stage::Operational;
}
Stage::Operational => return Err(Error::new(ErrorCode::InvalidState)),
Stage::CommissioningComplete => {
self.check_commissioning_error(fields)?;
self.stage = Stage::Done;
}
Stage::Done => return Err(Error::new(ErrorCode::InvalidState)),
}
Ok(())
}
pub fn on_operational(&mut self) -> Result<()> {
if self.stage != Stage::Operational {
return Err(Error::new(ErrorCode::InvalidState));
}
self.stage = Stage::CommissioningComplete;
Ok(())
}
#[must_use]
pub const fn pause(&self) -> bool {
matches!(self.stage, Stage::Operational)
}
fn encode<T: ToTlv>(&mut self, fields: &T) -> Result<()> {
let mut buf = [0u8; 1024];
let mut writer = TlvWriter::new_in(&mut buf, ContainerKind::Structure);
fields.to_tlv(&mut writer, Tag::Context(1))?;
let encoded = writer.finish()?;
self.fields = heapless::Vec::from_slice(encoded)
.map_err(|_| Error::new(ErrorCode::BufferTooSmall))?;
Ok(())
}
fn invoke(&self, cluster: ClusterId, command: CommandId) -> Step<'_> {
Step::Invoke {
endpoint: ROOT_ENDPOINT,
cluster,
command,
fields: &self.fields,
}
}
fn check_commissioning_error(&self, fields: Option<&[u8]>) -> Result<()> {
let decoded: general_commissioning::ArmFailSafeResponseFields<'_> =
decode(fields.ok_or_else(|| Error::new(ErrorCode::InvalidState))?)?;
if decoded.error_code != general_commissioning::CommissioningErrorEnum::OK {
return Err(Error::new(ErrorCode::CommissioningFailed));
}
Ok(())
}
fn check_noc_status(fields: Option<&[u8]>) -> Result<()> {
let decoded: operational_credentials::NOCResponseFields<'_> =
decode(fields.ok_or_else(|| Error::new(ErrorCode::InvalidState))?)?;
if decoded.status_code != operational_credentials::NodeOperationalCertStatusEnum::OK {
return Err(Error::new(ErrorCode::CommissioningFailed));
}
Ok(())
}
fn certificate(fields: Option<&[u8]>) -> Result<&[u8]> {
let decoded: operational_credentials::CertificateChainResponseFields<'_> =
decode(fields.ok_or_else(|| Error::new(ErrorCode::InvalidState))?)?;
Ok(decoded.certificate)
}
fn check_attestation(&mut self, fields: Option<&[u8]>) -> Result<()> {
let decoded: operational_credentials::AttestationResponseFields<'_> =
decode(fields.ok_or_else(|| Error::new(ErrorCode::InvalidState))?)?;
let signature = Signature::from_slice(decoded.attestation_signature)?;
let outcome = (|| -> Result<()> {
let dac = X509Certificate::parse(&self.dac)?;
if !verify_attestation(
&dac.public_key,
decoded.attestation_elements,
&self.challenge,
&signature,
)? {
return Err(Error::new(ErrorCode::AttestationFailed));
}
let elements = AttestationElements::decode(decoded.attestation_elements)?;
if elements.attestation_nonce != self.attestation_nonce {
return Err(Error::new(ErrorCode::AttestationFailed));
}
Ok(())
})();
self.attestation = Some(match outcome {
Ok(()) => Attestation::Trusted,
Err(error) => Attestation::Failed(error.code()),
});
Ok(())
}
pub fn verify_attestation_against(&mut self, paa_der: &[u8]) -> Result<Attestation> {
let outcome = (|| -> Result<()> {
let dac = X509Certificate::parse(&self.dac)?;
let pai = X509Certificate::parse(&self.pai)?;
let paa = X509Certificate::parse(paa_der)?;
verify_dac_chain(&dac, &pai, &paa)?;
Ok(())
})();
let result = match (self.attestation, outcome) {
(Some(Attestation::Failed(reason)), _) => Attestation::Failed(reason),
(_, Err(error)) => Attestation::Failed(error.code()),
(_, Ok(())) => Attestation::Trusted,
};
self.attestation = Some(result);
Ok(result)
}
fn check_csr(&mut self, fields: Option<&[u8]>) -> Result<()> {
let decoded: operational_credentials::CSRResponseFields<'_> =
decode(fields.ok_or_else(|| Error::new(ErrorCode::InvalidState))?)?;
let signature = Signature::from_slice(decoded.attestation_signature)?;
let dac = X509Certificate::parse(&self.dac)?;
if !verify_nocsr(
&dac.public_key,
decoded.nocsr_elements,
&self.challenge,
&signature,
)? {
return Err(Error::new(ErrorCode::AttestationFailed));
}
let elements = NocsrElements::decode(decoded.nocsr_elements)?;
if elements.csr_nonce != self.csr_nonce {
return Err(Error::new(ErrorCode::AttestationFailed));
}
let csr = Csr::parse(elements.csr)?;
if !crate::crypto::verify(&csr.public_key, csr.tbs, &csr.signature)? {
return Err(Error::new(ErrorCode::AttestationFailed));
}
self.operational_key = Some(csr.public_key);
Ok(())
}
}
fn decode<'a, T: crate::tlv::FromTlv<'a>>(fields: &'a [u8]) -> Result<T> {
let mut reader = crate::tlv::TlvReader::new_in(fields, ContainerKind::Structure);
let element = reader
.next_element()?
.ok_or_else(|| Error::new(ErrorCode::TlvTruncated))?;
T::from_tlv(&mut reader, &element)
}