7 releases

0.3.1 Aug 7, 2019
0.3.0 Aug 6, 2019
0.2.0 Jul 24, 2019
0.1.3 Mar 6, 2019
0.1.0 Dec 20, 2018

#1752 in Embedded development

MIT license

115KB
2K SLoC

GBL Firmware file manipulation library

crates.io docs.rs Build Status

Rust library for reading, creating and manipulating .gbl firmware update files.

Also check out this blog post for a gentle introduction into the crate's typestate-based API.

Features

  • Creating GBL files from raw application images
  • Parsing existing GBL files
  • Encrypt and sign GBL files
  • Decrypt GBL files and verify the embedded signature
  • Signing application images for secure boot
  • A simple command-line tool wrapping the library

Not yet supported

  • Bootloader image
  • Custom metadata sections

Command-line Usage

The command-line tool gbl can be installed by running cargo install in this directory. If you don't want to install it, you can also run it using cargo run. In that case, replace the gbl command with cargo run -- (for example, cargo run -- create --help).

The tool currently supports the following operations:

SUBCOMMANDS:
    app-image    Raw application image manipulation.
    create       Create a GBL file from raw application data.
    decrypt      Decrypts an encrypted GBL file with a shared AES key.
    dump         Parses an existing GBL file and dumps its structure to the console.
    encrypt      GBL firmware file handling library
    help         Prints this message or the help of the given subcommand(s)
    sign         Sign a GBL file using a private ECDSA key.
    verify       Verifies the signature of a signed GBL file.

Development

Fuzzing

You can run the included fuzzing targets (gbl or app_image) using

cargo +nightly fuzz run gbl

By default, libFuzzer won't produce inputs larger than 4096 bytes. To remedy this, use this command instead (you can use any max length you want, of course):

cargo +nightly fuzz run gbl -- -max_len=100000

Note that fuzz targets are not tested on CI and might break from time to time as the API changes. Feel free to fix them if this happens!

Benchmarks

Benchmarks use criterion and should be straighforward. Just do cargo bench.

Flame Graph

To generate a flame graph for a specific benchmark:

perf record --call-graph=dwarf target/release/deps/bench-<HASH> --measure-only '<BENCHMARK NAME>'
perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg

Make sure to use the same <HASH> Cargo displays when doing cargo bench.

Dependencies

~14–22MB
~421K SLoC