Crate sbat

UEFI SBAT (Secure Boot Advanced Targeting)

SBAT is used to revoke insecure UEFI executables in a way that won’t eat up the limited storage space available in the UEFI environment.

There are two important sources of data:

1. The SBAT metadata associated with each image describes the components in that image.
2. The SBAT revocation data stored in a UEFI variable provides a list of component versions that are no longer allowed to boot.

Each entry in the revocation list contains component name and version fields. (The first entry, which is the sbat version, also has a date field. That date field acts as a version for the whole revocation list.) When validating an image, each component in the image is checked against the revocation entries. If the name matches, and if the component’s version is less than the version in the corresponding revocation entry, the component is considered revoked and the image will not pass validation.

The details and exact validation rules are described further in the SBAT.md and SBAT.example.md files in the shim repo.

API

This no_std library handles parsing both sources of SBAT data (ImageSbat and RevocationSbat data), as well as performing the revocation comparison. The parsing starts with raw bytes containing the CSV; the library doesn’t handle directly reading PE binaries or UEFI variables. Consider using the object crate to extract the .sbat section from a PE binary.

If the alloc feature is enabled, the ImageSbatOwned and RevocationSbatOwned types can be be used. These types own the CSV string data rather than taking a reference to it. They deref to ImageSbat and RevocationSbat respectively.

Examples

use sbat::{ImageSbat, ParseError, RevocationSbat, ValidationResult};

fn main() -> Result<(), ParseError> {
    let image_sbat_a1 = b"sbat,1\nCompA,1";
    let image_sbat_a2 = b"sbat,1\nCompA,2";
    let revocation_sbat = b"sbat,1,2021030218\nCompA,2";

    // Parse the image and revocation SBAT.
    let image_sbat = ImageSbat::parse(image_sbat_a1)?;
    let revocations = RevocationSbat::parse(revocation_sbat)?;

    // Check that the image is revoked.
    assert_eq!(
        revocations.validate_image(image_sbat),
        ValidationResult::Revoked(image_sbat.entries().last().unwrap()),
    );

    // Change the image's CompA generation to 2 and verify that it is no
    // longer revoked.
    let image_sbat = ImageSbat::parse(image_sbat_a2)?;
    assert_eq!(
        revocations.validate_image(image_sbat),
        ValidationResult::Allowed,
    );

    Ok(())
}

Re-exports

pub use ValidationResult::Allowed;

pub use ValidationResult::Revoked;

Structs

Component

SBAT component. This is the machine-readable portion of SBAT that is actually used for revocation (other fields are human-readable and not used for comparisons).

Entries

Iterator over entries in ImageSbat.

Entry

Entry in image SBAT metadata. This contains a Component, which is what gets used for revocation comparisons, as well as Vendor data, which is extra data that serves as a human-readable comment.

Generation

SBAT component generation.

ImageSbat

Image SBAT metadata.

ImageSbatOwnedalloc

Owned image SBAT metadata.

RevocationSbat

Revocation SBAT data.

RevocationSbatOwnedalloc

Owned revocation SBAT data.

RevocationSection

Revocation data embedded in the .sbatlevel section of a shim executable.

RevokedComponents

Iterator over revoked components in RevocationSbat.

Vendor

Vendor data. This is optional human-readable data that is not used for SBAT comparison.

Enums

ParseError

SBAT parse error.

RevocationSectionError

Error returned by RevocationSection::parse.

ValidationResult

Whether an image is allowed or revoked.

Constants

ALLOWED_SPECIAL_CHARS

ASCII characters that this library allows in SBAT fields (in addition to alphanumeric characters).

REVOCATION_SECTION_NAME

Name of the revocation section embedded in shim executables.

SBAT_SECTION_NAME

Standard PE section name for SBAT metadata.