Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 30 additions & 11 deletions services/orchestrator/driver/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,45 @@ An effect whose capability is not composed yet returns `EffectError` from
`execute`; the SM fail-closes on it.

Everything device-specific arrives through the seams in `board.rs`
(`ImageSource`, `Verifier`, `BootControl`, `BootWatch`, bundled in `Board`).
Synchronous results (the verification verdict) return through `execute` and
settle within the same dispatch run — there is no driver-side event queue.
(`ImageSource`, `Verifier`, `BootControl`, `BootWatch`, bundled in `Board`). Nothing the
driver executes waits on a slow service. Short local calls (reset lines, the
SVN floor, reports) complete inside `execute`; the two long reads, the
verification verdict and the boot-walk verdicts, are polled. There is no
driver-side event queue.

Boot-walk verdicts are the one asynchronous read. `ReleaseReset` arms the
component's walk; the run loop polls and dispatches until quiet, then sleeps
until the earliest walk deadline:
`VerifyFirmware` starts a check and returns. The verdict arrives from
`poll_verify` as `VerificationPassed` or `VerificationFailed`; a verifier that
ran past its deadline reports `VerifyStatus::TimedOut`, which the driver
reports as `VerificationFailed` so the machine recovers the component. Starting
a check, or re-staging the image, cancels any check still outstanding, and its
answer is discarded. `ReleaseReset` arms the component's boot walk. The run
loop calls `poll`, dispatches each `Event` it returns, then sleeps on `Idle` until
`next_wake_millis` (the earlier of the earliest walk deadline and the verifier's
deadline) or a signal. It never sleeps without polling after the last dispatch,
because a new check's deadline is learnt only from its first poll. A
verifier that stops answering signals nothing, so its deadline is the only wake-up
that turns its silence into a failed verification:

```rust
orch.dispatch(&mut driver, event);
loop {
let poll = driver.poll_boot_walks(now_millis);
match poll.event {
Some(ev) => orch.dispatch(&mut driver, ev),
None => break, // poll.next_deadline_millis = next wake-up
// Read the clock each round.
match driver.poll(now_millis) {
// Something is ready: dispatch it, then poll again before sleeping.
Ok(DriverPoll::Event(ev)) => orch.dispatch(&mut driver, ev),
// Quiet: the only place the loop blocks. It wakes when a service
// signals or next_wake_millis passes, then polls again.
Ok(DriverPoll::Idle { next_wake_millis }) => {
object_wait(wait_group, Signals::READABLE, next_wake_millis)?;
}
// The check could not be carried through: fail closed, as an
// executor error does.
Err(_) => orch.dispatch(&mut driver, Event::EffectFailed),
}
}
```

Implemented executors: `ReadFirmware`, `VerifyFirmware`, `ReleaseReset`
Implemented executors: `ReadFirmware`, `VerifyFirmware` (starts the check), `ReleaseReset`
(arms the boot walk), `AssertReset` (stops it). Everything else fails closed
until its pillar lands (recovery, update path, attestation, reporting,
lockdown latch).
100 changes: 78 additions & 22 deletions services/orchestrator/driver/src/board.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,41 +47,97 @@ impl<S: ImageSource> ImageSource for &mut S {
}
}

/// Judges a component's firmware image; board wiring decides what counts
/// as authenticated.
/// Verifies a component's firmware image without making the caller wait.
///
/// The split mirrors `util_transport::AsyncTransport`: `start` begins a check
/// and returns, `poll` reports whether it has finished, and `cancel` abandons
/// it. A board whose check is a request to a crypto service implements this
/// directly, so the orchestrator keeps serving timers and events while the
/// image is hashed. A board whose check is fast and local completes it inside
/// `start` and answers `Done` on the first `poll`.
///
/// # How the run loop uses it
///
/// One check is outstanding at a time. The driver cancels before starting
/// another, so an implementation never holds two, and `poll` and `cancel`
/// name no component: they mean the check in flight.
///
/// 1. Call `start`, then call `poll` once straight away. A check that
/// finished inside `start` sends no signal, and the first `poll` is also
/// what reports the check's deadline.
/// 2. Sleep until the verifier signals or that deadline passes, then `poll`
/// again with the current time. A verifier that has stopped answering
/// sends no signal, so the deadline is the only thing that turns its
/// silence into [`VerifyStatus::TimedOut`].
///
/// Not object safe by design: `start` is generic over the image source, and a
/// board names its verifier through [`BoardCapabilities::Verifier`].
pub trait Verifier {
/// The error type reported by this verifier.
type Error: core::error::Error;

/// Judges `id`'s image, reading it from `image`.
/// Begins verifying `id`'s image. An implementation that reaches the image
/// itself, such as a service that reads it from the device server, may
/// ignore `image`.
///
/// # Errors
///
/// Only when the check could not be performed (crypto fault, missing
/// key, unreadable source). A checked-and-bad image is
/// `Ok(Verdict::Rejected)` — an actuation fault must not forge a
/// verdict.
fn verify(
&mut self,
id: ComponentId,
image: &mut impl ImageSource,
) -> Result<Verdict, Self::Error>;
/// Only when the check could not be started. A checked-and-bad image is
/// a [`Verdict::Rejected`] from `poll`, not an error here.
fn start(&mut self, id: ComponentId, image: &mut impl ImageSource) -> Result<(), Self::Error>;

/// Reports the outcome of the check in flight. Never waits. `now_millis`
/// is the current time, so an implementation with no clock of its own can
/// end a check that has run past its deadline with
/// [`VerifyStatus::TimedOut`].
///
/// # Errors
///
/// Only when the check could not be carried through (the service
/// failed, the transport broke). That is a fault, not a verdict. An
/// error ends the check.
fn poll(&mut self, now_millis: u64) -> Result<VerifyStatus, Self::Error>;

/// Abandons the check in flight. Its answer, if one arrives later, is
/// discarded.
fn cancel(&mut self) -> Result<(), Self::Error>;
}

impl<V: Verifier> Verifier for &mut V {
type Error = V::Error;

#[inline(always)]
fn verify(
&mut self,
id: ComponentId,
image: &mut impl ImageSource,
) -> Result<Verdict, Self::Error> {
(**self).verify(id, image)
fn start(&mut self, id: ComponentId, image: &mut impl ImageSource) -> Result<(), Self::Error> {
(**self).start(id, image)
}

#[inline(always)]
fn poll(&mut self, now_millis: u64) -> Result<VerifyStatus, Self::Error> {
(**self).poll(now_millis)
}

#[inline(always)]
fn cancel(&mut self) -> Result<(), Self::Error> {
(**self).cancel()
}
}

/// A [`Verifier`]'s judgment of one image.
/// Where an asynchronous check stands.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VerifyStatus {
/// Still running. `deadline_millis` is when the check will give up, on the
/// same clock as `poll`'s `now_millis`, or `None` if it has no deadline.
/// The run loop wakes then to poll again.
Pending { deadline_millis: Option<u64> },
/// Finished with a verification result.
Done(Verdict),
/// Ran past the implementation's deadline with no answer. Not a verdict:
/// nothing was verified. The driver reports it as a failed verification, so
/// the machine recovers the component instead of trusting or locking.
TimedOut,
}

/// A verifier's result for one image.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verdict {
/// Reported as `Event::VerificationPassed`. Carries the image's
Expand Down Expand Up @@ -164,7 +220,7 @@ impl<S: ReportSink> ReportSink for &mut S {
pub trait BoardCapabilities {
/// Image access for the managed components.
type Image: ImageSource;
/// Judges images for every component.
/// Verifies images for every component, without making the driver wait.
type Verifier: Verifier;
/// Reset actuation for the managed components.
type BootControl: BootControl;
Expand Down Expand Up @@ -199,7 +255,7 @@ pub enum SvnFloorBinding<F: SvnFloor> {
/// struct Ast1060Board;
/// impl BoardCapabilities for Ast1060Board {
/// type Image = SpiFlashImage; // interposed flash, offsets from the slot layout
/// type Verifier = ManifestVerifier; // signature + SVN via the crypto engine
/// type Verifier = ManifestVerifier; // signature + SVN via the crypto engine
/// type BootControl = ExtrstGpio; // per-component reset line
/// type BootWatch = CheckpointWalk; // GPIO checkpoint walk over the boot window
/// type SvnFloor = OtpSvnFloor; // fuse-backed anti-rollback floor
Expand All @@ -219,7 +275,7 @@ pub struct Board<B: BoardCapabilities, const N: usize> {
/// `images[i]` belongs to `ComponentId(i)` — device index = chain
/// position = table declaration order.
pub images: [B::Image; N],
/// Judges images for every component.
/// Verifies images for every component.
pub verifier: B::Verifier,
/// `boot_controls[i]` actuates `ComponentId(i)`'s reset, same indexing
/// as `images`.
Expand Down
Loading