diff --git a/.github/workflows/publish-guide-book.yml b/.github/workflows/publish-guide-book.yml index c233f6e..342869c 100644 --- a/.github/workflows/publish-guide-book.yml +++ b/.github/workflows/publish-guide-book.yml @@ -54,7 +54,7 @@ jobs: - name: Prepare and Build Track Books run: | # Reusable copy function for TOML and mermaid files - for TRACK in contributor embedded_controller integrator patina security value_proposition; do + for TRACK in contributor embedded_controller integrator security value_proposition; do cp -r guide_book/book.toml tracks/$TRACK/ cp -r guide_book/mermaid* tracks/$TRACK/ done @@ -63,8 +63,6 @@ jobs: mkdir -p tracks/value_proposition/src/why cp -r guide_book/src/why/* tracks/value_proposition/src/why/ - cp -r guide_book/src/intro/concepts/patina.md tracks/patina/src/patina_concepts.md - mkdir -p tracks/embedded_controller/src/images cp -r guide_book/src/intro/concepts/images/simplified_layers.png tracks/embedded_controller/src/images/ cp -r guide_book/src/intro/concepts/images/odp_arch.png tracks/embedded_controller/src/images/ @@ -72,12 +70,11 @@ jobs: cp -r guide_book/src/why/secure_trust.md tracks/security/src/secure_trust.md cp -r guide_book/src/architecture/security_architecture.md tracks/security/src/security_architecture.md - cp -r guide_book/src/architecture/secure_boot.md tracks/security/src/secure_boot.md cp -r guide_book/src/architecture/secure_firmware_updates.md tracks/security/src/secure_firmware_updates.md cp -r guide_book/src/architecture/secure_ec_services.md tracks/security/src/secure_ec_services.md # Build each track - for TRACK in contributor embedded_controller integrator patina security value_proposition; do + for TRACK in contributor embedded_controller integrator security value_proposition; do cd tracks/$TRACK mdbook clean mdbook build diff --git a/.gitignore b/.gitignore index b189ecb..8a7c292 100644 --- a/.gitignore +++ b/.gitignore @@ -41,9 +41,6 @@ tracks/engineer/mermaid.min.js tracks/integrator/book.toml tracks/integrator/mermaid-init.js tracks/integrator/mermaid.min.js -tracks/patina/book.toml -tracks/patina/mermaid-init.js -tracks/patina/mermaid.min.js tracks/security/book.toml tracks/security/mermaid-init.js tracks/security/mermaid.min.js @@ -60,13 +57,11 @@ tracks/embedded_controller/src/secure_ec_services.md tracks/security/src/secure_trust.md tracks/security/src/security_architecture.md -tracks/security/src/secure_boot.md tracks/security/src/secure_firmware_updates.md tracks/security/src/secure_ec_services.md # Ignore files duplicated for 'tracks' tracks\value_proposition\src\why -tracks\patina\src\patina_concepts.md tracks\embedded_controller\src\general.md tracks\embedded_controller\src\architecture.md @@ -76,7 +71,6 @@ tracks\embedded_controller\src\images tracks\security\src\secure_trust.md tracks\security\src\security_architecture.md -tracks\security\src\secure_boot.md tracks\security\src\secure_firmware_updates.md tracks\security\src\secure_ec_services.md diff --git a/.temp/build.bat b/.temp/build.bat index aeeb559..6f67d8b 100644 --- a/.temp/build.bat +++ b/.temp/build.bat @@ -15,8 +15,6 @@ copy ".\book.toml" "..\tracks\embedded_controller\" /Y copy ".\mermaid*" "..\tracks\embedded_controller\" /Y copy ".\book.toml" "..\tracks\integrator\" /Y copy ".\mermaid*" "..\tracks\integrator\" /Y -copy ".\book.toml" "..\tracks\patina\" /Y -copy ".\mermaid*" "..\tracks\patina\" /Y copy ".\book.toml" "..\tracks\security\" /Y copy ".\mermaid*" "..\tracks\security\" /Y copy ".\book.toml" "..\tracks\value_proposition\" /Y @@ -24,7 +22,6 @@ copy ".\mermaid*" "..\tracks\value_proposition\" /Y REM copy content shared across tracks xcopy ".\src\why\*" "..\tracks\value_proposition\src\why" /E /I /Y -xcopy ".\src\intro\concepts\patina.md" "..\tracks\patina\src\patina_concepts.md" /E /I /Y copy ".\src\intro\concepts\Embedded_controller.md" "..\tracks\embedded_controller\src\general.md" /Y copy ".\src\architecture\embedded_controller.md" "..\tracks\embedded_controller\src\architecture.md" /Y @@ -37,7 +34,6 @@ copy ".\src\intro\concepts\EC_Services.md" "..\tracks\embedded_controller\src\se copy ".\src\why\secure_trust.md" "..\tracks\security\src\secure_trust.md" /Y copy ".\src\architecture\security_architecture.md" "..\tracks\security\src\security_architecture.md" /Y -copy ".\src\architecture\secure_boot.md" "..\tracks\security\src\secure_boot.md" /Y copy ".\src\architecture\secure_firmware_updates.md" "..\tracks\security\src\secure_firmware_updates.md" /Y copy ".\src\architecture\secure_ec_services.md" "..\tracks\security\src\secure_ec_services.md" /Y @@ -56,10 +52,6 @@ cd ..\integrator mdbook clean mdbook build xcopy "book\*" "..\..\.temp\tracks\integrator" /E /I /Y -cd ..\patina -mdbook clean -mdbook build -xcopy "book\*" "..\..\.temp\tracks\patina" /E /I /Y cd ..\security mdbook clean mdbook build diff --git a/guide_book/src/SUMMARY.md b/guide_book/src/SUMMARY.md index 96ef3bc..a748cd9 100644 --- a/guide_book/src/SUMMARY.md +++ b/guide_book/src/SUMMARY.md @@ -10,18 +10,14 @@ - [Welcome Developer](./intro/welcome.md) - [Concepts](./intro/concepts/Concepts.md) - [A Quick Look at Rust](./intro/concepts/rust_quick_look.md) - - [Patina](./intro/concepts/patina.md) - [Sample System Implementation](./intro/concepts/ec_services_example/sample-system-implementation.md) - [Legacy EC Interface](./intro/concepts/ec_services_example/legacy_ec_interface.md) - [Secure EC Services](./intro/concepts/ec_services_example/secure-ec-services-overview.md) - [Architecture](./architecture/architecture.md) - - [Patina Framework](./architecture/patina_framework.md) - - [Component Model](./architecture/patina_components.md) - [Embedded Controller](./architecture/embedded_controller.md) - [Component Model](./architecture/ec_components.md) - [EC Services](./architecture/ec_services.md) - [Security Model](./architecture/security_architecture.md) - - [Secure Boot](./architecture/secure_boot.md) - [Firmware Updates](./architecture/secure_firmware_updates.md) - [Secure EC Services](./architecture/secure_ec_services.md) - [Tracks of ODP](./tracks.md) diff --git a/guide_book/src/architecture/patina_components.md b/guide_book/src/architecture/patina_components.md deleted file mode 100644 index 9bf2f78..0000000 --- a/guide_book/src/architecture/patina_components.md +++ /dev/null @@ -1,37 +0,0 @@ -# Patina Components - -Patina components are built according to Traits and introduced via Dependency Injection (DI) into the Patina framework. This allows for a modular and reusable design that can be easily adapted to different platforms and configurations. - -## Component Development - -Please refer to the [Patina documentation]() for more details, but the basic pseudo-code steps for creating a component are actually pretty simple: - -```rust -use log::info; -use patina_sdk::{component::params::Config, error::Result}; - -#[derive(Default, Clone, Copy)] -pub struct Name(pub &'static str); - -pub fn run_test_component(name: Config) -> Result<()> { - info!("============= Test Component ==============="); - info!("Hello, {}!", name.0); - info!("========================================="); - Ok(()) -} -``` -One creates a component as a function with parameters that implement the required traits (in this case the Config trait). The function can then be registered with the Patina framework, which will handle the dependency injection and execution of the component. - -```rust -Core::default() - .with_component(test_component::run_test_component) - .with_config(test_component::Name("World")) - .start() -``` - -What the component actually does is up to the developer, but the structure remains consistent. The component can be as simple or complex as needed, and it can interact with other components through the Patina framework's messaging system. - - -Refer to Patina's [component model documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/dxe_core/component_model.md) -and the Patina [dispatcher documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/dxe_core/dispatcher.md) -for official details on the component model and how to implement components in Patina. diff --git a/guide_book/src/architecture/patina_framework.md b/guide_book/src/architecture/patina_framework.md deleted file mode 100644 index fb169dc..0000000 --- a/guide_book/src/architecture/patina_framework.md +++ /dev/null @@ -1,24 +0,0 @@ -# Patina Framework Architecture - -Traditional UEFI architecture describes a series of boot phases that are executed in a specific order to initialize the system and prepare it for use. The Patina framework is designed to fit within this architecture, specifically focusing on the DXE (Driver Execution Environment) phase. - -![Boot Phases](./media/PI_Boot_Phases.jpg) - -Patina re-imagines the DXE phase as a framework for building modular, reusable components that can be dynamically loaded and executed. This approach allows for greater flexibility and agility in firmware development, enabling developers to create components that can be easily reused across different platforms and configurations. - -```mermaid -flowchart TD - A[UEFI] --> B[Patina Framework] - B --> C[Component Registration] - B --> D[EFI Binary Output] - B --> E[Platform Boot] - C --> F[Device Drivers] - E --> G[System Services] - E --> H[User Applications] - F --> G -``` -> #### Figure: Patina Framework within UEFI Boot Phases - -For architectural details, refer to the Patina [DXE Core documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/patina.md#patina-dxe-core). - - diff --git a/guide_book/src/architecture/secure_boot.md b/guide_book/src/architecture/secure_boot.md deleted file mode 100644 index 513c677..0000000 --- a/guide_book/src/architecture/secure_boot.md +++ /dev/null @@ -1,47 +0,0 @@ -# Secure Boot Architecture - -__Secure Boot__ is a cryptographically enforced boot validation mechanism that ensures each stage of system initialization is authenticated and unmodified. Its goal is to prevent unauthorized firmware or operating systems from executing on the platform. - -```mermaid -flowchart TD - A[__Boot ROM__
Immutable Trust Anchor] - B[__Bootloader__
- _e.g. BL1, Coreboot_] - C[__Patina DXE Core__
Signed EFI Binary] - D[__OS Bootloader__
_Optional Verification_] - E[__Operating System__
Signed Kernel and Drivers] - - A --> B - B --> C - C --> D - D --> E -``` -> __Figure: Secure Boot Chain of Trust__ -> -> Each stage validates the integrity and authenticity of the next using cryptographic signatures or measured hashes. Patina fits into this chain as the DXE-phase firmware payload, typically signed and validated prior to execution. - -## Role of Patina in Secure Boot - -1. The DXE Core produced by Patina is signed and stored as an .efi binary. -2. The platform bootloader (coreboot, U-Boot, etc.) or UEFI Secure Boot loader validates the Patina payload before execution. -3. Patina itself does not contain its own secure bootloader but is designed to be a signed leaf node in a secure boot chain. - -On platforms with measured boot (e.g., DRTM or TPM-backed environments), Patina binaries can also be hashed and extended into a PCR register. - -## Signature and Validation Workflow - -```mermaid -flowchart TD - A[__Patina EFI Binary__] - B[__Public Key__ - _in Bootloader_] - C[__Signature Verification__] - D[__Execution__] - - A --> C - B --> C - C -->|If Valid| D - C -->|If Invalid| E[Halt / Recovery] -``` - -A secure boot process is only one part of the platform's trust chain. To preserve integrity after boot, Firmware Updates must be signed and verified, and Runtime E access must be validated and isolated. - - diff --git a/guide_book/src/intro/concepts/patina.md b/guide_book/src/intro/concepts/patina.md deleted file mode 100644 index 1c0da65..0000000 --- a/guide_book/src/intro/concepts/patina.md +++ /dev/null @@ -1,127 +0,0 @@ -# Patina Background - -## Overview - -Firmware and UEFI firmware in particular has long been written in C. Firmware operates in a unique environment compared -to other system software. It is written to bootstrap a system often at the host CPU reset vector and as part of a chain -of trust established by a hardware rooted immutable root of trust. Modern PC and server firmware is extraordinarily -complex with little room for error. - -We call the effort to evolve and modernize UEFI firmware in the Open Device Partnership (ODP) project "Patina". The -remainder of this document will discuss the motivation for this effort, a high-level overview of the current state of -Patina, and the current state of Rust in UEFI firmware. - -### Firmware Evolution - -From a functional perspective, firmware must initialize the operating environment of a device. To do so involves -integrating vendor code for dedicated microcontrollers, security engines, individual peripherals, System-on-Chip (SOC) -initialization, and so on. Individual firmware blobs may be located on a number of non-volatile media with very limited -capacity. The firmware must perform its functional tasks successfully or risk difficult to diagnose errors in higher -levels of the software stack that may impede overall device usability and debuggability. - -These properties have led to slow but incremental expansion of host firmware advancements over time. - -![Host FW Evolution](./images/uefi_evolution.png) - -### Firmware Security - -From a security perspective, firmware is an important component in the overall system Trusted Computing Base (TCB). -Fundamental security features taken for granted in later system software such as kernels and hypervisors are often -based on secure establishment in a lower layer of firmware. At the root is a concept of "trust". - -While operating systems are attractive targets due to their ubiquity across devices and scale, attackers are -beginning to shift more focus to firmware as an attack surface in response to increasingly effective security measures -being applied in modern operating systems. While significant research has been devoted across the entire boot process, -UEFI firmware on the host CPU presents a unique opportunity to gain more visibility into early code execution details -and intercept the boot process before essential activities take place such as application of important security -register locks, cache/memory/DMA protections, isolated memory regions, etc. The result is code executed in this -timeframe must carry forward proper verification and measurement of future code while also ensuring it does not -introduce a vulnerability in its own execution. - -### Performant and Reliable - -From a performance perspective, firmware code is often expected to execute exceedingly fast. The ultimate goal is for -an end user to not even be aware such code is present. In a consumer device scenario, a user expects to press a power -button and immediately receive confirmation their system is working properly. At a minimum, a logo is often shown to -assure the user something happened and they will be able to interact with the system soon. In a server scenario, -fleet uptime is paramount. Poorly written firmware can lead to long boot times that impact virtual machine -responsiveness and workload scaling or, even worse, Denial of Service if the system fails to boot entirely. In an -embedded scenario, government regulations may require firmware to execute fast enough to show a backup camera within a -fixed amount of time. - -All of this is to illustrate that firmware must perform important work in a diverse set of hardware states with code -that is as small as possible and do so quickly and securely. In order to transition implementation spanning millions of -lines of code written in a language developed over 50 years ago requires a unique and compelling alternative. - -## Rust and Firmware - -As previously stated, modern systems necessitate a powerful language that can support low-level programming with -maximum performance, reliability, and safety. While C has provided the flexibility needed to implement relatively -efficient firmware code, it has failed to prevent recurring problems around memory safety. - -### Stringent Safety - -Common pitfalls in C such as null pointer dereferences, buffer and stack overflows, and pointer mismanagement continue -to be at the root of high impact firmware vulnerabilities. These issues are especially impactful if they compromise -the system TCB. Rust is compelling for UEFI firmware development because it is designed around strong memory safety -without the usual overhead of a garbage collector. In addition, it enforces stringent type safety and concurrency rules -that prevent the types of issues that often lead to subtle bugs in low-level software development. - -Languages aside, UEFI firmware has greatly fallen behind other system software in its adoption of basic memory -vulnerability mitigation techniques. For example, data execution protection, heap and stack guards, stack cookies, -and null pointer dereference detection is not present in the vast majority of UEFI firmware today. More advanced -(but long time) techniques such as Address Space Layout Randomization (ASLR), forward-edge control flow integrity -technologies such as x86 Control Flow Enforcement (CET) Indirect Branch Tracking (IBT) or Arm Branch Target -Identification (BTI) instructions, structured exception handling, and similar technologies are completely absent in -most UEFI firmware today. This of course exacerbates errors commonly made as a result of poor language safety. - -Given firmware code also runs in contexts with high privilege level such as System Management Mode (SMM) in x86, -implementation errors can be elevated by attackers to gain further control over the system and subvert other -protections. - -### Developer Productivity - -The Rust ecosystem brings more than just safety. As a modern language firmware development can now participate -in concepts and communities typically closed to firmware developers. For example: - -- Higher level multi-paradigm programming concepts such as those borrowed from functional programming in addition to - productive polymorphism features such as generics and traits. - -- Safety guarantees that prevent errors and reduce the need for a myriad of static analysis tools with flexibility to - still work around restrictions when needed in an organized and well understood way (unsafe code). - -### Modern Tooling - -Rust includes a modern toolchain that is well integrated with the language and ecosystem. This standardizes tooling -fragmented across vendors today and lends more time to firmware development. Examples of tools and community support: - -- An official package management system with useful tools such as first-class formatters and linters that reduce - project-specific implementations and focus discussion on functional code changes. - -- High quality reusable bundles of code in the form of crates that increase development velocity and engagement with - other domain experts. - -- Useful compilation messages and excellent documentation that can assist during code development. - -- A modern testing framework that allows for unit, integration, and on-platform tests to be written in a consistent - way. Code coverage tools that are readily available and integrate seamlessly with modern IDEs. - -Rust's interoperability with C code is also useful. This enables a phased adoption pathway where codebases can start -incorporating Rust while still relying upon its extensive pre-existing code. At the same time, Rust has been conscious -of low-level needs and can precisely structure data for C compatibility. - -## Patina in ODP - -The Patina team in ODP plans to participate within the open Rust development community by: - -1. Engaging with the broader Rust community to learn best practices and share low-level system programming knowledge. -2. Leveraging and contributing back to popular crates and publishing new crates that may be useful to other projects. - - A general design strategy is to solve common problems in a generic crate that can be shared and then integrate it - back into firmware. -3. Collaborating with other firmware vendors and the UEFI Forum to share knowledge and best practices and - incorporate elements of memory safety languages like Rust into industry standard specifications where appropriate. - Some specifications have interfaces defined around concepts and practices common in unsafe languages that could - be improved for safety and reliability. - -Looking forward, we're continuing to expand the coverage of our firmware code written in Rust. We are excited to -continue learning more about Rust in collaboration with the community and our partners. diff --git a/guide_book/src/intro/getting_started.md b/guide_book/src/intro/getting_started.md index 76b2936..c61fdcf 100644 --- a/guide_book/src/intro/getting_started.md +++ b/guide_book/src/intro/getting_started.md @@ -28,7 +28,7 @@ In the [Tracks of ODP](../tracks.md), you will find curated content organized in | __Integrator__ | Read through the Architectural Overview and Integration sections, then follow the [Integrator Track](../../tracks/integrator/track_overview.md) for platform-specific setup and bundling guidance. | | __Contributor__ | Review the mainline Value Proposition and Architecture Overview, then head to the [Contributor Track](../../tracks/contributor/track_overview.md) for community, contribution standards, and roadmap content. | | __Security Reviewer__ | Jump to the [Security Track](../../tracks/security/track_overview.md). It includes collected topics around trusted boot, isolation, and other security concerns, with cross-links to affected design areas. | -| __Patina SDK (UEFI) Developer__ | Refer to external Patina resources with context provided in the [Patina Track](../../tracks/patina/track_overview.md). You’ll find links to upstream Patina crates, code examples, and implementation notes. | +| __Patina SDK (UEFI) Developer__ | Refer to external Patina resources: the [Patina Book](https://opendevicepartnership.github.io/patina/) for guides and concepts, and the [Patina source repository](https://github.com/opendevicepartnership/patina) for crates, code examples, and implementation notes. | --- diff --git a/guide_book/src/intro/welcome.md b/guide_book/src/intro/welcome.md index afe81e3..d205d3b 100644 --- a/guide_book/src/intro/welcome.md +++ b/guide_book/src/intro/welcome.md @@ -4,9 +4,8 @@ Welcome! If you're a firmware engineer new to the Open Device Partnership, this If you're also new to the world of Embedded Controllers and the software that drives them, don't worry — you're still in the right place. -If you are a previous UEFI developer, you may find some of the concepts familiar, but ODP introduces new patterns and practices that will help you build more secure and modular firmware components. ODP introduces Patina, a Rust-based framework that provides a modern approach to firmware development, focusing on safety, modularity, and reusability. Patina honors the legacy and traditions of UEFI while introducing new paradigms that make firmware development more efficient and secure. -For more specific information about Patina, you can refer to the [Patina Track](../../tracks/patina/track_overview.md) or the [Patina Concepts](./intro/concepts/patina.md) section. - +If you are a previous UEFI developer, you may find some of the concepts familiar, but ODP introduces new patterns and practices that will help you build more secure and modular firmware components. ODP introduces Patina, a Rust-based framework that provides a modern approach to firmware development, focusing on safety, modularity, and reusability. Patina honors the legacy and traditions of UEFI while introducing new paradigms that make firmware development more efficient and secure. +For more specific information about Patina, you can refer to the [Patina Book](https://opendevicepartnership.github.io/patina/) or the [Patina source repository](https://github.com/opendevicepartnership/patina). |   |   |---|--- diff --git a/guide_book/src/laptop/integrating.md b/guide_book/src/laptop/integrating.md index dfc304a..8fd3e71 100644 --- a/guide_book/src/laptop/integrating.md +++ b/guide_book/src/laptop/integrating.md @@ -45,7 +45,7 @@ This is where the line between “virtual” and “real” blurs: the host does ## Step 5: Add a Patina Boot Layer Next, layer in the host firmware: -- Follow the [Patina](../architecture/patina_framework.md) resources online to build a Patina DXE Core image +- Follow the [Patina](https://opendevicepartnership.github.io/patina/) resources online to build a Patina DXE Core image - Add only the minimal DXE components needed to initialize ACPI and speak to the EC. This gives your virtual laptop a complete boot firmware stage. diff --git a/guide_book/src/overview.md b/guide_book/src/overview.md index 6198afd..a0cb422 100644 --- a/guide_book/src/overview.md +++ b/guide_book/src/overview.md @@ -10,7 +10,7 @@ Then the different 'tracks' of ODP will be explained. Here, you may find you ar Then, what is inside ODP and where to find it is detailed further - this is a good resource for those simply wishing to navigate the maze of contributed repositories that are available and which ones fit together for a given task. -Patina (boot firmware) documentation is covered conceptually in this guide. Developers wishing to dig into code examples for this aspect of ODP should follow the resources outlined in the [**Patina Track**](../tracks/patina/track_overview.md). +Patina (boot firmware) documentation is covered in the [**Patina Book**](https://opendevicepartnership.github.io/patina/). Developers wishing to dig into code or examples should refer to the [**Patina source repository**](https://github.com/opendevicepartnership/patina). Finally, for developers wishing to know more about how all of this comes together for an Embedded Controller, a series of example implementation exercises are detailed. These exercises can be explored per-component, or as a series that culminates in a working integration with a simulation application and test. diff --git a/guide_book/src/tracks.md b/guide_book/src/tracks.md index 3b05600..eb9d54c 100644 --- a/guide_book/src/tracks.md +++ b/guide_book/src/tracks.md @@ -20,17 +20,16 @@ If you are a __Firmware Engineer__ you likely will want to continue following ah Depending on your interest or role, we offer guided tracks through the documentation: #### Subject-based: + - 🏅 [**Value Proposition**](../tracks/value_proposition/track_overview.md) Understand the core benefits of ODP, including security, modularity, and cross-domain coherence. -- 🛫 [**Patina Boot Firmware**](../tracks/patina/track_overview.md) +- 🛫 [**Patina Boot Firmware**](https://opendevicepartnership.github.io/patina/) Learn to build UEFI firmware with Rust using the Patina framework. - 🔐 [**Security Architecture**](../tracks/security/track_overview.md) Explore trusted boot, firmware identity, and the DICE model. - - #### Role-based: - 🔧 [**Integrator**](../tracks/integrator/track_overview.md) diff --git a/tracks/integrator/src/SUMMARY.md b/tracks/integrator/src/SUMMARY.md index 9fc49aa..78ee8f3 100644 --- a/tracks/integrator/src/SUMMARY.md +++ b/tracks/integrator/src/SUMMARY.md @@ -1,6 +1,5 @@ [Overview](./track_overview.md) [Integration Facets](./facets.md) -[Patina Integration Overview](./patina.md) [Shared Patterns and Divergences](./shared_patterns.md) [Preparing for Hardware Targets](./hardware_targets.md) diff --git a/tracks/integrator/src/patina.md b/tracks/integrator/src/patina.md deleted file mode 100644 index 4c1590e..0000000 --- a/tracks/integrator/src/patina.md +++ /dev/null @@ -1,14 +0,0 @@ -# Patina Integration - -Integration approaches for Patina are covered at [Patina DXE Core Platform Integration](https://sturdy-adventure-nv32gqw.pages.github.io/integrate/patina_dxe_core_requirements.html) - -This is part of the larger [Developer documentation for Patina](https://sturdy-adventure-nv32gqw.pages.github.io/) that should be fully reviewed before attempting integrations. - -Integration for a virtual environment for examples or testing may benefit from the QEMU support repositories - -- [QEMU DXE Core Binaries](https://github.com/openDevicePartnership/patina-dxe-core-qemu?tab=readme-ov-file#qemu-dxe-core-binaries) -- [Patina Platform Repository](https://github.com/openDevicePartnership/patina-qemu?tab=readme-ov-file#patina-platform-repository) - -Find other Patina relevant repositories in the -[What's in ODP?](../../guide/what/what.md) table. - diff --git a/tracks/patina/src/SUMMARY.md b/tracks/patina/src/SUMMARY.md deleted file mode 100644 index a6d82a7..0000000 --- a/tracks/patina/src/SUMMARY.md +++ /dev/null @@ -1,3 +0,0 @@ -[Overview](./track_overview.md) -[Patina Background](./patina_concepts.md) -[More Patina Links](./more_patina.md) \ No newline at end of file diff --git a/tracks/patina/src/images/uefi_evolution.png b/tracks/patina/src/images/uefi_evolution.png deleted file mode 100644 index f3e17de..0000000 Binary files a/tracks/patina/src/images/uefi_evolution.png and /dev/null differ diff --git a/tracks/patina/src/more_patina.md b/tracks/patina/src/more_patina.md deleted file mode 100644 index 2df4fd0..0000000 --- a/tracks/patina/src/more_patina.md +++ /dev/null @@ -1,9 +0,0 @@ -# Additional Patina Resources - -You can find more resources related to Patina in the following locations: - -[Developing UEFI with Rust](https://sturdy-adventure-nv32gqw.pages.github.io/) - -[Patina Repository](https://github.com/OpenDevicePartnership/patina?tab=readme-ov-file#patina) - -[Other repositories](../../guide/what/what.md) diff --git a/tracks/patina/src/patina_concepts.md b/tracks/patina/src/patina_concepts.md deleted file mode 100644 index 1c0da65..0000000 --- a/tracks/patina/src/patina_concepts.md +++ /dev/null @@ -1,127 +0,0 @@ -# Patina Background - -## Overview - -Firmware and UEFI firmware in particular has long been written in C. Firmware operates in a unique environment compared -to other system software. It is written to bootstrap a system often at the host CPU reset vector and as part of a chain -of trust established by a hardware rooted immutable root of trust. Modern PC and server firmware is extraordinarily -complex with little room for error. - -We call the effort to evolve and modernize UEFI firmware in the Open Device Partnership (ODP) project "Patina". The -remainder of this document will discuss the motivation for this effort, a high-level overview of the current state of -Patina, and the current state of Rust in UEFI firmware. - -### Firmware Evolution - -From a functional perspective, firmware must initialize the operating environment of a device. To do so involves -integrating vendor code for dedicated microcontrollers, security engines, individual peripherals, System-on-Chip (SOC) -initialization, and so on. Individual firmware blobs may be located on a number of non-volatile media with very limited -capacity. The firmware must perform its functional tasks successfully or risk difficult to diagnose errors in higher -levels of the software stack that may impede overall device usability and debuggability. - -These properties have led to slow but incremental expansion of host firmware advancements over time. - -![Host FW Evolution](./images/uefi_evolution.png) - -### Firmware Security - -From a security perspective, firmware is an important component in the overall system Trusted Computing Base (TCB). -Fundamental security features taken for granted in later system software such as kernels and hypervisors are often -based on secure establishment in a lower layer of firmware. At the root is a concept of "trust". - -While operating systems are attractive targets due to their ubiquity across devices and scale, attackers are -beginning to shift more focus to firmware as an attack surface in response to increasingly effective security measures -being applied in modern operating systems. While significant research has been devoted across the entire boot process, -UEFI firmware on the host CPU presents a unique opportunity to gain more visibility into early code execution details -and intercept the boot process before essential activities take place such as application of important security -register locks, cache/memory/DMA protections, isolated memory regions, etc. The result is code executed in this -timeframe must carry forward proper verification and measurement of future code while also ensuring it does not -introduce a vulnerability in its own execution. - -### Performant and Reliable - -From a performance perspective, firmware code is often expected to execute exceedingly fast. The ultimate goal is for -an end user to not even be aware such code is present. In a consumer device scenario, a user expects to press a power -button and immediately receive confirmation their system is working properly. At a minimum, a logo is often shown to -assure the user something happened and they will be able to interact with the system soon. In a server scenario, -fleet uptime is paramount. Poorly written firmware can lead to long boot times that impact virtual machine -responsiveness and workload scaling or, even worse, Denial of Service if the system fails to boot entirely. In an -embedded scenario, government regulations may require firmware to execute fast enough to show a backup camera within a -fixed amount of time. - -All of this is to illustrate that firmware must perform important work in a diverse set of hardware states with code -that is as small as possible and do so quickly and securely. In order to transition implementation spanning millions of -lines of code written in a language developed over 50 years ago requires a unique and compelling alternative. - -## Rust and Firmware - -As previously stated, modern systems necessitate a powerful language that can support low-level programming with -maximum performance, reliability, and safety. While C has provided the flexibility needed to implement relatively -efficient firmware code, it has failed to prevent recurring problems around memory safety. - -### Stringent Safety - -Common pitfalls in C such as null pointer dereferences, buffer and stack overflows, and pointer mismanagement continue -to be at the root of high impact firmware vulnerabilities. These issues are especially impactful if they compromise -the system TCB. Rust is compelling for UEFI firmware development because it is designed around strong memory safety -without the usual overhead of a garbage collector. In addition, it enforces stringent type safety and concurrency rules -that prevent the types of issues that often lead to subtle bugs in low-level software development. - -Languages aside, UEFI firmware has greatly fallen behind other system software in its adoption of basic memory -vulnerability mitigation techniques. For example, data execution protection, heap and stack guards, stack cookies, -and null pointer dereference detection is not present in the vast majority of UEFI firmware today. More advanced -(but long time) techniques such as Address Space Layout Randomization (ASLR), forward-edge control flow integrity -technologies such as x86 Control Flow Enforcement (CET) Indirect Branch Tracking (IBT) or Arm Branch Target -Identification (BTI) instructions, structured exception handling, and similar technologies are completely absent in -most UEFI firmware today. This of course exacerbates errors commonly made as a result of poor language safety. - -Given firmware code also runs in contexts with high privilege level such as System Management Mode (SMM) in x86, -implementation errors can be elevated by attackers to gain further control over the system and subvert other -protections. - -### Developer Productivity - -The Rust ecosystem brings more than just safety. As a modern language firmware development can now participate -in concepts and communities typically closed to firmware developers. For example: - -- Higher level multi-paradigm programming concepts such as those borrowed from functional programming in addition to - productive polymorphism features such as generics and traits. - -- Safety guarantees that prevent errors and reduce the need for a myriad of static analysis tools with flexibility to - still work around restrictions when needed in an organized and well understood way (unsafe code). - -### Modern Tooling - -Rust includes a modern toolchain that is well integrated with the language and ecosystem. This standardizes tooling -fragmented across vendors today and lends more time to firmware development. Examples of tools and community support: - -- An official package management system with useful tools such as first-class formatters and linters that reduce - project-specific implementations and focus discussion on functional code changes. - -- High quality reusable bundles of code in the form of crates that increase development velocity and engagement with - other domain experts. - -- Useful compilation messages and excellent documentation that can assist during code development. - -- A modern testing framework that allows for unit, integration, and on-platform tests to be written in a consistent - way. Code coverage tools that are readily available and integrate seamlessly with modern IDEs. - -Rust's interoperability with C code is also useful. This enables a phased adoption pathway where codebases can start -incorporating Rust while still relying upon its extensive pre-existing code. At the same time, Rust has been conscious -of low-level needs and can precisely structure data for C compatibility. - -## Patina in ODP - -The Patina team in ODP plans to participate within the open Rust development community by: - -1. Engaging with the broader Rust community to learn best practices and share low-level system programming knowledge. -2. Leveraging and contributing back to popular crates and publishing new crates that may be useful to other projects. - - A general design strategy is to solve common problems in a generic crate that can be shared and then integrate it - back into firmware. -3. Collaborating with other firmware vendors and the UEFI Forum to share knowledge and best practices and - incorporate elements of memory safety languages like Rust into industry standard specifications where appropriate. - Some specifications have interfaces defined around concepts and practices common in unsafe languages that could - be improved for safety and reliability. - -Looking forward, we're continuing to expand the coverage of our firmware code written in Rust. We are excited to -continue learning more about Rust in collaboration with the community and our partners. diff --git a/tracks/patina/src/track_overview.md b/tracks/patina/src/track_overview.md deleted file mode 100644 index e8ba6b5..0000000 --- a/tracks/patina/src/track_overview.md +++ /dev/null @@ -1,2 +0,0 @@ -# ODP Patina Track Overview -The Patina track is designed for individuals who are interested in developing and maintaining the Patina framework within the Open Device Partnership (ODP). This track focuses on the design, implementation, and testing of Patina solutions, which are essential for creating efficient and scalable applications. Readers will learn how to leverage the Patina framework to build robust applications that enhance user experience, improve performance, and ensure system reliability. \ No newline at end of file diff --git a/tracks/security/src/SUMMARY.md b/tracks/security/src/SUMMARY.md index 67a81d1..1175428 100644 --- a/tracks/security/src/SUMMARY.md +++ b/tracks/security/src/SUMMARY.md @@ -1,6 +1,5 @@ - [Overview](./track_overview.md) - [Secure Foundations](./secure_trust.md) - [Secure Architecture](./security_architecture.md) -- [Secure Boot](./secure_boot.md) - [Secure Firmware Updates](./secure_firmware_updates.md) - [Secure EC Services](./secure_ec_services.md) diff --git a/tracks/security/src/secure_boot.md b/tracks/security/src/secure_boot.md deleted file mode 100644 index 513c677..0000000 --- a/tracks/security/src/secure_boot.md +++ /dev/null @@ -1,47 +0,0 @@ -# Secure Boot Architecture - -__Secure Boot__ is a cryptographically enforced boot validation mechanism that ensures each stage of system initialization is authenticated and unmodified. Its goal is to prevent unauthorized firmware or operating systems from executing on the platform. - -```mermaid -flowchart TD - A[__Boot ROM__
Immutable Trust Anchor] - B[__Bootloader__
- _e.g. BL1, Coreboot_] - C[__Patina DXE Core__
Signed EFI Binary] - D[__OS Bootloader__
_Optional Verification_] - E[__Operating System__
Signed Kernel and Drivers] - - A --> B - B --> C - C --> D - D --> E -``` -> __Figure: Secure Boot Chain of Trust__ -> -> Each stage validates the integrity and authenticity of the next using cryptographic signatures or measured hashes. Patina fits into this chain as the DXE-phase firmware payload, typically signed and validated prior to execution. - -## Role of Patina in Secure Boot - -1. The DXE Core produced by Patina is signed and stored as an .efi binary. -2. The platform bootloader (coreboot, U-Boot, etc.) or UEFI Secure Boot loader validates the Patina payload before execution. -3. Patina itself does not contain its own secure bootloader but is designed to be a signed leaf node in a secure boot chain. - -On platforms with measured boot (e.g., DRTM or TPM-backed environments), Patina binaries can also be hashed and extended into a PCR register. - -## Signature and Validation Workflow - -```mermaid -flowchart TD - A[__Patina EFI Binary__] - B[__Public Key__ - _in Bootloader_] - C[__Signature Verification__] - D[__Execution__] - - A --> C - B --> C - C -->|If Valid| D - C -->|If Invalid| E[Halt / Recovery] -``` - -A secure boot process is only one part of the platform's trust chain. To preserve integrity after boot, Firmware Updates must be signed and verified, and Runtime E access must be validated and isolated. - -