Skip to main content

OperationalCredentials

Struct OperationalCredentials 

Source
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 */
}
Available on crate feature 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>

Source

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.

Source

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.

Source

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>

Source

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.

Source

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.

Source

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>

Source

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.

Source

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.

Source

pub fn update_fabric_label( &self, label: &str, ctx: &InteractionContext<'_>, ) -> Result<NocStatus, Status>

UpdateFabricLabel (§11.18.6.11).

Source

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.

Source

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.

Source

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>

Source

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.

Trait Implementations§

Source§

impl<C: Config, K: KeyStore, R: Rng, const N: usize> Cluster for OperationalCredentials<'_, C, K, R, N>

Source§

const ID: ClusterId = ID

The cluster id this implementation serves.
Source§

impl<C: Config, K: KeyStore, R: Rng, const N: usize> ClusterHandler for OperationalCredentials<'_, C, K, R, N>

Source§

fn read( &self, resolved: &Resolved<'_>, ctx: &InteractionContext<'_>, w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<(), Status>

Writes the value of resolved’s attribute under tag. Read more
Source§

fn invoke( &self, resolved: &ResolvedCommand<'_>, fields: Option<&[u8]>, ctx: &InteractionContext<'_>, w: &mut TlvWriter<'_>, tag: Tag, ) -> Result<Option<CommandId>, StatusIb>

Runs a command. Read more
Source§

fn data_version(&self, _resolved: &Resolved<'_>) -> Option<u32>

The cluster instance’s data version (§7.10.3), if it tracks one. Read more
Source§

fn write( &self, _resolved: &Resolved<'_>, _data: &[u8], _op: WriteOp, _ctx: &InteractionContext<'_>, ) -> Result<(), Status>

Writes data — the encoded TLV element, tag included — into the attribute. Read more
Source§

fn on_lifecycle(&self, _event: Lifecycle)

Reacts to something that happened to the node (see Lifecycle). Read more

Auto Trait Implementations§

§

impl<'a, C, K, R, const N: usize> !Freeze for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> !RefUnwindSafe for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> !Send for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> !Sync for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> !UnwindSafe for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> Forget for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> Move for OperationalCredentials<'a, C, K, R, N>

§

impl<'a, C, K, R, const N: usize> Unpin for OperationalCredentials<'a, C, K, R, N>
where &'a RefCell<FabricTable<C, N>>: Unpin, &'a RefCell<K>: Unpin, &'a RefCell<R>: Unpin,

§

impl<'a, C, K, R, const N: usize> UnsafeUnpin for OperationalCredentials<'a, C, K, R, N>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.