# GBL Firmware file manipulation library
[](https://crates.io/crates/gbl)
[](https://docs.rs/gbl/)
[](https://travis-ci.org/dac-gmbh/gbl)
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.
[this blog post]: https://blog.1aim.com/post/gbl-release/
## 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](https://github.com/japaric/criterion.rs) 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>'
Make sure to use the same `<HASH>` Cargo displays when doing `cargo bench`.