Crate gbl

Method and apparatus for creating, parsing and manipulating GBL firmware update files.

GBL files are used to implement Over-the-Air (OTA) updates for some microcontrollers. GBL is a container format wrapping the actual flash image. GBL container files can optionally be encrypted and signed.

Existing GBL files can be loaded using Gbl::from_bytes, an application image can be packed into a GBL file using Gbl::from_app_image.

In addition to that, the crate also contains utilities for reading and signing raw application images created by the firmware build process, which can be used to enable secure boot. Refer to the AppImage type and the below example for details.

Examples

Demonstrates signing an app image for secure boot, then building, signing and encrypting a GBL file containing it:

let image_bytes = include_bytes!("../test-data/empty/empty.bin");
let signing_key = include_str!("../test-data/signing-key");  // in PEM format
let encrypt_key = include_str!("../test-data/aes-key-tokens");

let image = AppImage::parse(image_bytes.as_ref())?;
let signed_image = image.sign(signing_key)?;

let gbl = Gbl::from_app_image(signed_image);
// Use `gbl.push_data_section` here to add more data to the container
let encrypted = gbl.encrypt(AesKey::from_token_file(encrypt_key)?);
let signed = encrypted.sign(signing_key)?;

Attempting many kinds of invalid operations (here, encrypting a GBL after signing it), will fail to compile due to invalid typestate:

let gbl = Gbl::from_app_image(image);
let signed = gbl.sign(signing_key)?;
let encrypted = signed.encrypt(aes_key);

error[E0599]: no method named `encrypt` found for type `gbl::Gbl<gbl::marker::NotEncrypted<'_>, gbl::marker::Signed<'_>>` in the current scope
  --> src/lib.rs:57:24
   |
17 | let encrypted = signed.encrypt(aes_key);
   |                        ^^^^^^^

The correct order of operations would be to encrypt before signing the GBL, which compiles fine:

let gbl = Gbl::from_app_image(image);
let encrypted = gbl.encrypt(aes_key);
let signed = encrypted.sign(signing_key)?;

Re-exports

pub extern crate uuid;

Modules

marker

Contains marker types used to implement type state for encrypted and signed GBLs.

Structs

AesKey	A symmetric AES-128 encryption/decryption key.
AppImage	A flash image containing application data.
AppInfo	An application info structure.
Error	The error type used by this library.
Gbl	In-memory representation of a GBL file.
ProgramData	A chunk of program data to be programmed to a specified flash address.

Enums

ErrorKind

The different kinds of errors that can occur.