Introduction

A bpak archive is composed of a 4kByte header and parts. A part is any kind of data. The header contains a list of parts, a list of meta data and details about how the package should be hashed and signed. 2kBytes are reserved for actual metadata within the header.

The metadata header encodes and id, size and offset within the metadata block of the header. An optional part-reference can be populated if the metadata belongs to a specific part.

Bitpacker id’s are generated by computing a crc32 checksum of a character string. For example the package identifier type ‘bpak-package’, when translated using the bpak_id-function results in bpak_id(‘bpak-package’) = 0xfb2f1f3f.

To facilitate efficient over-the-air updates a bpak file can be encoded for transport. In transport some or all parts are encoded, typically using the bsdiff algorithm.

Bitpacker supports two different signing schemes, one where the private key is available on disk which is appropriate for un-controlled development keys but makes life easier for day-to-day development. The second way is to export a binary hash that can be signed in a controlled environment. Bitpacker supports retrofitting DER formatted signatures, which, for example, is what openssl can produce. This way an approved release candidate can be re-signed with production keys without rebuilding all the artefacts that make up a bpak archive.

Limitations

Bitpacker is not a complete package management system, it provides some necessary low level primitives that can enable such a system. If you choose to use it there is likely a lot of integration work that needs to be done before it is useful in any sense of the word.

The library and format does not specify how to install a package and therefore left as an implementation detail.

Bitpacker is new and not really supported by any other projects except the punchboot bootloader (https://github.com/jonasblixt/punchboot)

The library does not include any cryptographic API or functionality, it only comes with a structure for storing signatures and some concepts to enable signature verification and key management.

Well known metadata id’s

ID	Encoding	Description
0xfb2f1f3f	UUID	bpak-package, Package identifier type
0x9a5bab69	char[]	bpak-version, Version string
0x0ba87349	<UUID, char>	bpak-dependency, Dependency tuple, UUID reference to another package and text string expressing constraints
0x2d44bbfb	<uint32, uint32>	bpak-transport, Transport medadata contains int32 pair that describes which encoder and decoder should be used for transport

Built in transport algorithms

ID	Name	Description
0xb5bcc58f	merkle-generate	This decoder builds a merkle hash tree out of part data
0x57004cd0	remove-data	Encoder that strips data from a part during transport encoding
0x9f7aacf9	bsdiff	Encoder that creates a binary diff of a part given some other original part
0xb5964388	bspatch	Decoder that reverses the operation of bspatch
0xe31722a6	heatshrink-encode	Heatshrink compression algorithm
0x5f9bc012	heatshrink-decode	Heatshrink decompression algorithm

Versioning

The bitpacker tool and library uses semver 2.0.0 versioning