pub struct OperationalCredentials<'a, C: Config, K: KeyStore, R: Rng, const N: usize> {
pub fabrics: &'a RefCell<FabricTable<C, N>>,
pub keys: &'a RefCell<K>,
pub rng: &'a RefCell<R>,
pub fail_safe: &'a RefCell<FailSafe>,
pub attestation: DeviceAttestation<'a>,
/* private fields */
}rustcrypto only.Expand description
The Operational Credentials cluster.
Holds nothing itself: the fabric table, the key store and the fail-safe are all node state this cluster manipulates on the wire’s behalf. That is what makes it shareable with CASE (which needs the same fabric table) and with General Commissioning (which arms the same fail-safe).
Fields§
§fabrics: &'a RefCell<FabricTable<C, N>>The fabric table — the Fabrics, NOCs and TrustedRootCertificates attributes.
keys: &'a RefCell<K>Key custody. CSRRequest generates into it and RemoveFabric destroys from it.
rng: &'a RefCell<R>The node’s one source of entropy, for CSRRequest’s key generation.
A trait rather than raw bytes, because this is driven by the interaction model rather than called directly — and it is still a parameter, so a test installs a deterministic generator and gets a reproducible key.
fail_safe: &'a RefCell<FailSafe>The fail-safe every credential-changing command runs inside (§11.10.7.2).
attestation: DeviceAttestation<'a>This product’s attestation material.
Implementations§
Source§impl<'a, C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'a, C, K, R, N>
impl<'a, C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'a, C, K, R, N>
Sourcepub fn new(
fabrics: &'a RefCell<FabricTable<C, N>>,
keys: &'a RefCell<K>,
rng: &'a RefCell<R>,
fail_safe: &'a RefCell<FailSafe>,
attestation: DeviceAttestation<'a>,
) -> Self
pub fn new( fabrics: &'a RefCell<FabricTable<C, N>>, keys: &'a RefCell<K>, rng: &'a RefCell<R>, fail_safe: &'a RefCell<FailSafe>, attestation: DeviceAttestation<'a>, ) -> Self
The cluster over a device’s fabric table, key store and fail-safe.
Sourcepub fn take_change(&self) -> Option<FabricChange>
pub fn take_change(&self) -> Option<FabricChange>
Takes the work the last credential-changing command left behind.
A device calls this after every invoke against this cluster. Forgetting to means a fabric is joined with no administrator able to reach it (§11.18.6.8 step 7), or a removed fabric’s sessions stay open.
Sourcepub fn discard_pending(&self)
pub fn discard_pending(&self)
Discards any fail-safe-scoped state, destroying the operational key a CSRRequest
generated and nothing used.
Call this when the fail-safe expires — it is §11.10.7.2.2 step 8, “the new operational key pair temporarily generated for the purposes of NOC addition or update … SHALL be removed as it is no longer needed” — and it is idempotent.
Source§impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
Sourcepub fn attestation_response(
&self,
nonce: &[u8; 32],
timestamp: u32,
challenge: &SymmetricKey,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<(), Status>
pub fn attestation_response( &self, nonce: &[u8; 32], timestamp: u32, challenge: &SymmetricKey, w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<(), Status>
AttestationRequest (§11.18.6.1) → AttestationResponse (§11.18.6.2).
Writes AttestationElements [0] and AttestationSignature [1] under tag.
The signature is over attestation_elements_message || attestation_challenge, and the
elements are signed exactly as they will be sent — not re-encoded. A device whose
encoder differed from its signer’s by one octet would produce a response no
commissioner could verify, and the failure would look like a bad key.
Sourcepub fn csr_response(
&self,
nonce: &[u8; 32],
for_update: bool,
ctx: &InteractionContext<'_>,
random: &[u8; 32],
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<(), Status>
pub fn csr_response( &self, nonce: &[u8; 32], for_update: bool, ctx: &InteractionContext<'_>, random: &[u8; 32], w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<(), Status>
CSRRequest (§11.18.6.5) → CSRResponse (§11.18.6.6).
Generates a fresh operational key pair, builds a PKCS#10 CSR over it, and signs the
whole nocsr_elements_message with the attestation key. Two signatures over two
different things: the CSR’s own proves possession of the new operational key, and the
outer one binds the request to the attested device and the live session.
Sourcepub fn add_trusted_root(
&self,
rcac: &[u8],
ctx: &InteractionContext<'_>,
) -> Result<(), Status>
pub fn add_trusted_root( &self, rcac: &[u8], ctx: &InteractionContext<'_>, ) -> Result<(), Status>
AddTrustedRootCertificate (§11.18.6.13).
No response command: success is a plain SUCCESS status. The certificate is pending
until an AddNOC adopts it — §11.18.6.13 is explicit that the only way to remove a
trusted root is to remove the fabric that uses it, so one installed by a fail-safe
that then expired must never have been installed at all.
Source§impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
Sourcepub fn add_noc(
&self,
request: &AddNocRequest<'_>,
ctx: &InteractionContext<'_>,
) -> Result<NocStatus, Status>
pub fn add_noc( &self, request: &AddNocRequest<'_>, ctx: &InteractionContext<'_>, ) -> Result<NocStatus, Status>
AddNOC (§11.18.6.8) — join a fabric.
Returns the StatusCode for the NOCResponse, and on success records a
FabricChange::Added for OperationalCredentials::take_change.
Every failure here “SHALL leave all non-volatile state of the device untouched, as if
the AddNOC command had never been received. The information about the last CSR state
associated with this session SHALL also be untouched in this case, so that a valid
AddNOC command MAY still be issued later that would match that CSR state.” So the
pending key is consumed only on the success path — a commissioner that sent a
malformed NOC gets to try again without another CSRRequest.
Sourcepub fn update_noc(
&self,
noc: &[u8],
icac: Option<&[u8]>,
ctx: &InteractionContext<'_>,
) -> Result<NocStatus, Status>
pub fn update_noc( &self, noc: &[u8], icac: Option<&[u8]>, ctx: &InteractionContext<'_>, ) -> Result<NocStatus, Status>
UpdateNOC (§11.18.6.9) — rotate the operational key and certificate on a fabric
this node already belongs to.
Sourcepub fn update_fabric_label(
&self,
label: &str,
ctx: &InteractionContext<'_>,
) -> Result<NocStatus, Status>
pub fn update_fabric_label( &self, label: &str, ctx: &InteractionContext<'_>, ) -> Result<NocStatus, Status>
UpdateFabricLabel (§11.18.6.11).
Sourcepub fn remove_fabric(
&self,
index: FabricIndex,
ctx: &InteractionContext<'_>,
) -> Result<NocStatus, Status>
pub fn remove_fabric( &self, index: FabricIndex, ctx: &InteractionContext<'_>, ) -> Result<NocStatus, Status>
RemoveFabric (§11.18.6.12) — leave a fabric, and delete everything scoped to it.
The index is a parameter, not the accessing fabric: an administrator may remove a
fabric other than its own, which is why the command is A rather than AF. The three
outcomes §11.18.6.12 distinguishes differ only in what else goes with it, and
FabricChange::Removed carries which one happened.
Sourcepub fn set_vid_verification_statement(
&self,
vendor_id: Option<VendorId>,
statement: Option<&[u8]>,
vvsc: Option<&[u8]>,
ctx: &InteractionContext<'_>,
) -> Result<(), Status>
pub fn set_vid_verification_statement( &self, vendor_id: Option<VendorId>, statement: Option<&[u8]>, vvsc: Option<&[u8]>, ctx: &InteractionContext<'_>, ) -> Result<(), Status>
SetVIDVerificationStatement (§11.18.6.14).
All three fields are optional and at least one must be present (O.a+). The command
“SHALL only operate against the Fabrics and NOCs attribute entries associated with the
accessing fabric index”, which is what AF enforces before it reaches here.
Sourcepub fn sign_vid_verification(
&self,
index: FabricIndex,
client_challenge: &[u8; 32],
ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<(), Status>
pub fn sign_vid_verification( &self, index: FabricIndex, client_challenge: &[u8; 32], ctx: &InteractionContext<'_>, w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<(), Status>
SignVIDVerificationRequest (§11.18.6.15) → SignVIDVerificationResponse
(§11.18.6.16).
Signs §6.4.10’s vendor_id_verification_tbs with the operational key of the fabric
under verification — not the attestation key. The procedure proves that whoever holds
that fabric’s NOC stands behind the VendorID the fabric claims, which is a statement
about the fabric rather than about the hardware.
Source§impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
impl<C: Config, K: KeyStore, R: Rng, const N: usize> OperationalCredentials<'_, C, K, R, N>
Sourcepub fn run(
&self,
command: CommandId,
fields: Option<&[u8]>,
ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<Option<CommandId>, Status>
pub fn run( &self, command: CommandId, fields: Option<&[u8]>, ctx: &InteractionContext<'_>, w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<Option<CommandId>, Status>
Runs one command of §11.18.6.
This is what ClusterHandler::invoke forwards to; it is public because the
commands are worth driving directly from a test or a controller-side harness.