microsoft / mu_feature_uefi_variable

Project Mu - Feature Repo - UEFI Variables

Project Mu UEFI Variables

This repository contains a prototype for a new UEFI variable design for modern PCs.

It is extensible, secure, with built-in testing up and down the entire stack. The design and implementation are all taking place here in this repo.

Project Mu Top-Level information

This repository is part of Project Mu. Please see Project Mu for details: https://microsoft.github.io/mu.

Current Project Status

This project is not actively being developed. There are plans to implement the design currently shown in this repo in the future and those will be shared on the repo when finalized.

Contributing

We welcome everyone to file feature requests, bugs, participate in code reviews, submit code, update documentation, and help us build the best variable driver possible.

At this time, we are very early in the work so we're particularly interested in ideas around the future of UEFI variables (including breaking UEFI specification compatibility) and suggestions to help shape the overall design.

Please open GitHub issues directly in this repo.

Background

The UEFI Specification describes an interface between the operating system (OS) and platform firmware. A UEFI Specification compliant system must implement two high-level sets of services - Boot Services which consist of functions available prior to a successful call to EFI_BOOT_SERVICES.ExitBootServices() and Runtime Services which consist of functions that are available before and after any call to EFI_BOOT_SERVICES.ExitBootServices().

A fundamental Runtime Service is called the UEFI variable services. These services are comprised of an API that the platform firmware must implement to satisfy the relevant API requirements defined in the UEFI Specification. While the underlying implementation is platform-specific, the callers will include both the operating system and firmware components.

Motivation

The de facto open-source implementation of UEFI, TianoCore, provides a commonly used set of UEFI variable drivers in the edk2 project that has served as the industry standard implementation for UEFI variable services for over a decade. Over time, the UEFI variable driver has substantially grown in complexity to support an increasing number of features.

The TianoCore driver is now over 15 years old. It's design is rigid and not accommodating to change. Over the span of its lifetime, many advancements have occurred in the PC industry that require better scale to support:

1. New storage technologies have come to market
2. Device trends have shifted to low-power ultra mobile devices and cloud server systems
3. New offload engines like BMC and special security processors have become more common to process non-volatile data
4. New expectations around device security have come into focus
   • For example, resistance against physical attack has led to variable data confidentiality via encryption, data integrity checks for tamper-proof storage guarantees, data replay protection, etc.
5. Additional computer architectures have gained popularity such as AArch64 and RISC-V
6. Operating systems have evolved and so have their security expectations

The TianoCore driver was written for a PI-centric boot flow assuming it was writing to SPI flash with no structured design to support extending the driver to support these advancements. In addition, while some industry standard tests such as the UEFI Self-Certification Tests exist, much of the stack is error prone to modify and difficult to assess because of its accumulated technical debt.

Due to the importance of the driver, we concluded that a new design that takes into account these requirements with testing built in could better support today's needs.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct https://opensource.microsoft.com/codeofconduct/

For more information see the Code of Conduct FAQ https://opensource.microsoft.com/codeofconduct/faq/ or contact [email protected]. with any additional questions or comments.

Builds

Please follow the steps in the Project Mu docs to build for CI and local testing. More Details

Copyright & License

Some files in this repository have their own copyright. Otherwise, the following copyright applies.

Copyright (C) Microsoft Corporation
SPDX-License-Identifier: BSD-2-Clause-Patent

mu_feature_uefi_variable's Issues

Stores: Describe the Store Policy

Describe the policy schema used to describe variable stores.

For example:

• The store name
• The store security properties
• The store read/write capabilities
• The store size
• Etc.

Project Management: Add ability to auto assign the project

To help reduce contributor effort, the "Project Mu UEFI Variables" project should be automatically assigned upon issue and pull request creation.

User-Facing API: Define Security API

Describe the main API users interact with to security UEFI variables.

Example of a security operation:

• Lock ( )

The descriptions must include:

1. API name
2. API purpose
3. Formal parameter list
4. Return value
5. Overall side effects

Design: Describe Initial High-Level Design

An initial design needs to be established to use as a starting point for the project.

Compatibility Gasket: Describe UEFI Spec compatibility requirements

Assuming we create a new UEFI variable API independent of the UEFI Spec requirements, we would like to have a drop-in replacement for code already written to the UEFI Spec interfaces.

This task is to describe how a UEFI Spec compatible interface could be connected to the variable front-end.

Remove pull_request trigger from add-to-project GitHub action

Since GitHub treats workflows triggered from forks (and Dependabot) as untrusted, they receive a read-only GITHUB_TOKEN and the PRs cannot access any secrets in the repository.

More information:
https://github.blog/changelog/2021-02-19-github-actions-workflows-triggered-by-dependabot-prs-will-run-with-read-only-permissions/

The trigger type could be changed to pull_request_target which would grant permission to the secrets but it has security implications as described here: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/

In the end, we'll just remove the action for pull requests for now.

API Validator: Describe validation requirements

Describe what the API validator needs to validate.

Depends on the API defined in #9, #10, #11

VariablePkg: Create initial package contents

An initial package needs to be created that simply contains a DSC file so it can build.

This will allow actual changes to be made on the package in the future and support enabling a back set of build pipelines hooked into mu_devops

Security: Describe the Security Validator Policy

Assume that we have a security validator element. Describe its policy schema to allow the validator to assume many of the responsibilities of "UEFI Variable Policy" in the past.

For example:

• Variable access constraints
• Variable size constraints
• Etc.

This will require some knowledge of how the variable interface accepts user input as defined in #9.

Stores: Describe the Store API

Stores need a well-defined and standardized API for the router to use for interacting with the store.

Describe the common store API used to interact with stores.

Examples of potential operations might include:

• Write ( )
• Delete ( )
• GarbageCollect ( )
• Etc.

Router: Describe the Router Policy

Describe the policy schema used by the router to choose which stores to associate with a given variable transaction.

For example:

• Route based on variable GUID
• Route based on variable name
• Route based on security policy
• Etc.

User-Facing API: Define Access API

Describe the main API users interact with to access UEFI variables.

Examples of access operations:

• Read ( )
• Write ( )
• Copy ( )
• Delete ( )

The descriptions must include:

1. API name
2. API purpose
3. Formal parameter list
4. Return value
5. Overall side effects

SBAT: Gather requirements for the variable design

List the requirements for Secure Boot Advanced Targeting (SBAT) or an SBAT-like capability.

1. Define what capabilities are needed to efficiently revoke code based on vulnerabilities
   • Example: Revocation by image hash, metadata (e.g. company, product, etc.)
2. Describe the information needed to support these capabilities
   • What information does a user need to provide to make use of the capabilities defined in (1)

[Documentation]: Document upcoming work plan

Request Description

Put together upcoming planned work.

Are you going to make the change?

I will make the change

Do you need maintainer feedback?

No maintainer feedback needed

Anything else?

No response

Security: Add CodeQL workflow

Add a CodeQL workflow to the repo for VariablePkg so the results are available in GitHub Code Scanning and in the Actions page.

Trusted Execution Environments: Define abstraction details

This task is to define how Trusted Execution Environments (TEEs) will be abstracted.

Examples of TEEs include:

• Arm TrustZone
• Intel SGX Enclaves
• x86 System Management Mode (SMM)

For example, I think we might need an Init ( ) method to initialize the TEE. Probably a Communicate ( ) method to send a message to a TEE.

The main idea is that regardless of the underlying TEE, the interface used to interact with it should be the same and substituting a TEE should no result in any code changes to TEE callers.

SBAT: Describe integration with the variable design

Building upon #7, describe how the requirements will be met with the presently defined Project Mu UEFI variable design.

1. Using variable design terminology, what elements will be involved?
2. What policy will those elements need?
3. Do these requirements necessitate introducing new elements or design modifications?

User-Facing API: Describe Store API

Describe the main API users interact with to access UEFI variable store.

I'm not entirely sure this is needed. An outcome of this task might be a conclusion we don't need a user API for stores.

Examples of store operations might include:

• AddStore ( )
• LockStore ( )

The descriptions must include:

1. API name
2. API purpose
3. Formal parameter list
4. Return value
5. Overall side effects

Security: Define authentication flow

Describe what level of "authenticated variables" should be supported.

This is a high-level task to start definition of this topic and it might split into subtasks such as:

• How is authentication actually achieved? What needs to be done?
• What are the interfaces used to perform authentication? Or how does authentication affect existing interfaces?
• How is authenticated support achieved within this variable design?

CI: Add "VariablePkg"

The initial package planned for this repo needs to be added to CI against VS2022 and GCC build targets.