Crate sbat

source ·
Expand description

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, but it is purely cosmetic.) 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.

Two variations of the API are provided:

Examples

use sbat::{
    ImageSbat, ImageSbatArray, ParseError, RevocationSbat, RevocationSbatArray,
    ValidationResult,
};
#[cfg(feature = "alloc")]
use sbat::{ImageSbatVec, RevocationSbatVec};

const IMAGE_SBAT_A1: &[u8] = b"sbat,1\nCompA,1";
const IMAGE_SBAT_A2: &[u8] = b"sbat,1\nCompA,2";
const REVOCATION_SBAT: &[u8] = b"sbat,1,2021030218
CompA,2";

/// This example uses fixed-size array types that do not allocate.
#[test]
fn example_fixed_size() -> Result<(), ParseError> {
    // Parse the image and revocation SBAT.
    let image_sbat = ImageSbatArray::<10>::parse(IMAGE_SBAT_A1)?;
    let revocations = RevocationSbatArray::<10>::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 1 and verify that it is no
    // longer revoked.
    let image_sbat = ImageSbatArray::<10>::parse(IMAGE_SBAT_A2)?;
    assert_eq!(
        revocations.validate_image(&image_sbat),
        ValidationResult::Allowed,
    );

    Ok(())
}

/// This example uses `Vec`-like types that dynamically allocate.
#[cfg(feature = "alloc")]
#[test]
fn example_vec() -> Result<(), ParseError> {
    // Parse the image and revocation SBAT.
    let image_sbat = ImageSbatVec::parse(IMAGE_SBAT_A1)?;
    let revocations = RevocationSbatVec::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 1 and verify that it is no
    // longer revoked.
    let image_sbat = ImageSbatVec::parse(IMAGE_SBAT_A2)?;
    assert_eq!(
        revocations.validate_image(&image_sbat),
        ValidationResult::Allowed,
    );

    Ok(())
}

Re-exports

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).
  • 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.
  • ImageSbatArray
    Image SBAT metadata.
  • ImageSbatVec
    Image SBAT metadata.
  • PushError
    Error returned by try_push if the underlying storage is out of space.
  • RevocationSbatArray
    SBAT revocation data.
  • RevocationSbatVec
    SBAT revocation data.
  • Vendor
    Vendor data. This is optional human-readable data that is not used for SBAT comparison.

Enums

Constants

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

Traits