Security: Clean disable of boot image and hardware before handoff to app image

[gregshue]

Introduction

The handoff of execution from a boot image to an application image needs to not leak security information out of the boot image. This means that all hardware and memory data (e.g., stack image) needs to be cleaned up before the handoff. Since Zephyr is a composable system this needs a general solution that supports composability. The natural solution is to extend the system initialization feature to also support a shutdown in reverse-dependency order. This enables delaying the handoff until persistent data and hardware agents (DMA, interrupt controllers) are in a clean state expected at the handoff point.

Problem description

Currently the Zephyr system APIs do not seem to have a way to clean up the hardware and memory before handing off execution to a new image. This opens the door for leaking information from the boot image to the app image.

Proposed change

Extend the System Initialization API to also support a system shutdown in reverse dependency order. This is to be executed by the same thread that ran system initialization calls.

Detailed RFC

See Proposed change

Proposed change (Detailed)

In zephyr/include/init.h:

• Extend struct init_entry with a shutdown handler: `int (*shutdown)(const struct device *dev);
• Update existing macros using struct init_entry to initialize the shutdown field to NULL
• Add *_INIT_SHUTDOWN* macros parallel to *_INIT* macros, that expose both the _init_fn, and _shutdown_fn parameters.
• Add a void z_sys_shutdown_enable(void); method to enable shutdown calls once main() is returned from.

In zephyr/kernel/init.c:

• Extend initialization code to call the shutdown methods in reverse dependency order, verifying the return codes indicate success.

Dependencies

This change:

• increases the size of struct init_entry by at least the size of a pointer.
• requires components (subsystems and drivers) to honor the shutdown request by
  • supporting and honoring callback un-registrations from clients
  • unregistering any notifications this component registered for
  • completing or aborting work-in-progress
  • cancelling outstanding asynchronous operations (including DMAs, interrupt controllers, timers, crypto algorithm states)
  • no longer calling other components or using OS services
  • failing API calls when in a shutdown state

Concerns and Unresolved Questions

None recognized

Alternatives

The following alternatives were considered:

1. A separate, independent shutdown handler registration: Registering the shutdown handler independent from the init handler requires describing the dependency order in multiple places, increasing the risk of mis-configuration.
2. Creating an assert handler registration and using this for controlled shutdown: Though an assert handler must be able to re-initialize hardware to a safe (secure?) condition at any point in time, it does not require it be left in a condition appropriate for handoff to another executable. Assert() is distinctly catastrophic.

[ceolin]

Security WG to add security requirements.

[ceolin]

** Example use cases

• Secure Boot-to-Application Handoff
• Multi-Image Systems
• Secure Device Reboot
  • Prevents undefined behavior or security risks during reboot by guaranteeing a consistent starting state.
• Error Recovery
  • Shutdown API can facilitate resetting to a safe state before reinitializing components.
• Firmware Updates
  • Ensures a seamless update process without residual states interfering with the new firmware.

** Functional Requirements

• Allow for the shutdown process to execute in reverse dependency order.
  • Ensure that shutdown handlers are called in reverse order of initialization, respecting dependency relationships between subsystems and drivers.
• Resource Cleanup
  • Ensure that hardware resources (DMA, interrupt controllers, timers) are returned to a known, clean state.
  • Clear sensitive memory areas (e.g., stack, heap) to prevent security leaks during handoff.
• Component Shutdown Behavior
  • Subsystems and drivers must:
    • Unregister any client callbacks and notifications.
    • Complete or abort work-in-progress tasks.
    • Cancel any outstanding asynchronous operations (DMAs, timers, etc.).
    • Ensure no further interactions with other components or OS services after shutdown initiation.
    • Return error codes for API calls attempted during or after shutdown.
      - System State Validation
    • Add mechanisms to validate that all components have entered a clean shutdown state before executing the final handoff.

** Non-Functional Requirements

• Minimal Overhead
  • Keep the increase in struct init_entry size minimal (pointer-sized addition).
  • Optimize shutdown process to minimize impact on performance and memory usage.
• Security
  • Ensure that the shutdown process leaves no residual sensitive data in memory or hardware registers.
  • Provide logging for debugging but avoid including sensitive information.
• Reliability
  • Robust error handling for failures in shutdown handlers.
  • Ensure that the system remains in a recoverable state if the shutdown process encounters errors.
• Scalability
  • Allow for a modular and composable system design, supporting a wide variety of subsystem and driver configurations.
  • Ensure the solution scales for systems with complex dependency trees.
• Ease of Integration
  • Provide clear documentation and examples to help developers implement and test shutdown handlers in their subsystems and drivers.

[gregshue]

Observations on the above list:

1. facilitate resetting to a safe state before reinitializing components:
   AFAICT, Zephyr seems to not be designed for a run-time reinitialization of components. It will be nearly impossible to guarantee the digital circuits are restored to a safe state without going through an electrical reset. Similarly, "reinitializing components" is going to be nearly impossible without resetting all the initialized memory. This is why it is so difficult to write drivers that run during catastrophic error handling (when the driver must take over running HW in an unknown state).

2. Logging for debugging:
   Security regulations are going to require a security log be kept on devices. These logs will need to retain security event information that will be written by bootloader code and read (written?) by application code. This may be substantially different than the content in typical Zephyr "LOG_" calls. It may justify a different API.

3. Allow for the shutdown process to execute:
   AFAICT the reverse shutdown order is necessary. "Allow" seems inappropriate. Do you have a real use case where a non-reverse-shutdown-order is necessary?

4. Cancel any outstanding asynchronous operations (DMAs, timers, etc.).
   Beware, many SOCs I have worked with do not support cancelling each DMA operation.

5. Ensure no further interactions with other components or OS services after shutdown initiation:
   Shutdown initiation begins with the entering the first shutdown handler (last component to be initialized). This handler will be using other components to enact its internal shutdown. For a clean shutdown this handling may need to be done on a component-internal thread, then release the thread calling the shutdown handler. The same pattern will occur in every component. Also, I don't see how the shutdown framework can "ensure" the claim above.

6. systems with complex dependency trees:
   Fundamentally, the SYS_INIT() mechanism imposes an overall Client-Server FW architecture. This means that the dependencies will follow a Directed Acyclic Graph (DAG). No matter how many dependencies exist reversing the initialization order of a DAG is trivial.

7. The fundamental question is what thread will call the shutdown handlers. AFAICT the only reasonable candidate is the same thread calling SYS_INIT() (which already has an appropriately sized stack). This means the default implementation of main() needs to be able to return when triggered.

Consider: In a single-threaded configuration (e.g., bootloader) the default main() should return success. In a multi-threaded configuration the default main() could simply suspend itself before returning success.

Additional Functional Requirements:

• Device automatically recovers if app image handoff fails. (This effectively means the HW watchdog is running across the handoff.)
• Configuration options for Individual GPIO pins/pads to be retained across handoff. (Use case: Avoid tri-stating UART pins that would result in resetting other devices on the shared UART lines.