`bpak_core` — BPAK Core library¶

This documents the BPAK core library. This constitutes the minimum set of useful features of the BPAK library.

It contains the functions for parsing and manipulating the header and the metadata.

Source code: include/bpak/bpak.h, lib/bpak.c

BPAK - Bit Packer

SPDX-License-Identifier: BSD-3-Clause

Defines

BPAK_HEADER_MAGIC¶: Magic number for BPAK header identification

BPAK_MAX_PARTS¶: Maximum number of data parts a package can have

BPAK_MAX_META¶: Maximum number of metadata fields a package can have

BPAK_METADATA_BYTES¶: Maximum number of bytes allocated for metadata

BPAK_PART_ALIGN¶: Minimum alignment of data parts

BPAK_META_ALIGN¶

BPAK_SIGNATURE_MAX_BYTES¶: Maximum size of signature

BPAK_FLAG_EXCLUDE_FROM_HASH¶

BPAK_FLAG_TRANSPORT¶

BPAK_MIN(__a, __b)¶: Helper macro to return the smaller of two values

bpak_foreach_part(__hdr, __var)¶: Helper macro to iterate over all parts in a package

bpak_foreach_meta(__hdr, __var)¶: Helper macro to iterate over all metadata in a package

Enums

enum bpak_hash_kind¶

BPAK Hash identifier

Values:

enumerator BPAK_HASH_INVALID¶

enumerator BPAK_HASH_SHA256¶

enumerator BPAK_HASH_SHA384¶

enumerator BPAK_HASH_SHA512¶

enum bpak_signature_kind¶

BPAK signature format

Values:

enumerator BPAK_SIGN_INVALID¶

enumerator BPAK_SIGN_RSA4096¶

enumerator BPAK_SIGN_PRIME256v1¶

enumerator BPAK_SIGN_SECP384r1¶

enumerator BPAK_SIGN_SECP521r1¶

enum bpak_errors¶

BPAK Result codes

Values:

enumerator BPAK_OK¶

enumerator BPAK_FAILED¶

enumerator BPAK_NOT_FOUND¶

enumerator BPAK_SIZE_ERROR¶

enumerator BPAK_NO_SPACE_LEFT¶

enumerator BPAK_BAD_ALIGNMENT¶

enumerator BPAK_SEEK_ERROR¶

enumerator BPAK_NOT_SUPPORTED¶

enum bpak_header_pos¶

The BPAK header can be in the begining or the end of a file or block device

Values:

enumerator BPAK_HEADER_POS_FIRST¶

enumerator BPAK_HEADER_POS_LAST¶

Functions

int bpak_get_meta(struct bpak_header *hdr, uint32_t id, void **ptr)¶

Retrive pointer to metadata with id ‘id’. If *ptr equals NULL the function will search from the beginning of the header array. When *ptr points to some data within the metadata block, the function will search forward from that point.

Return

BPAK_OK on success -BPAK_NOT_FOUND if the metadata is missing

Parameters

[in] hdr: BPAK Header
[in] id: Meta data identifier
[out] ptr: Pointer is assigned to the location of the metadata within the hdr->metadata byte array.

int bpak_get_meta_with_ref(struct bpak_header *hdr, uint32_t id, uint32_t part_id_ref, void **ptr)¶

Get pointer to meta data with ‘id’ and a part reference id ‘part_id_ref’. Similar to bpak_get_meta but with the added part_id_ref parameter

Return

BPAK_OK on success -BPAK_NOT_FOUND if the metadata is missing

Parameters

[in] hdr: BPAK Header
[in] id: Meta data identifier
[in] part_id_ref: Part reference identifier
[out] ptr: Pointer is assigned to the location of the metadata within the hdr->metadata byte array.

int bpak_get_meta_and_header(struct bpak_header *hdr, uint32_t id, uint32_t part_id_ref, void **ptr, struct bpak_meta_header **header)¶

Get pointer to both the metadata header and the actual data

Return

BPAK_OK on success -BPAK_NOT_FOUND if the metadata is missing

Parameters

[in] hdr: BPAK Header
[in] id: Meta data identifier
[in] part_id_ref: Part reference identifier
[out] ptr: Pointer is assigned to the location of the metadata within the hdr->metadata byte array.
[out] header: Pointer to the metadata header

int bpak_add_meta(struct bpak_header *hdr, uint32_t id, uint32_t part_ref_id, void **ptr, uint16_t size)¶

Add new metadata with id ‘id’ of size ‘size’. *ptr is assigned to a pointer within the hdr->metadata byte array.

Return

BPAK_OK on success or -BPAK_NO_SPACE if the metadata array is full

Parameters

[in] hdr: BPAK Header
[in] id: ID of new metadata
[in] part_ref_id: Optional part reference to use for new metadata
[out] ptr: Output pointer to allocated metadata
[in] size: Size in bytes of new metadata

int bpak_get_part(struct bpak_header *hdr, uint32_t id, struct bpak_part_header **part)¶

Retrive pointer to part with id ‘id’.

part pointer is assigned to the location of the part header within the hdr->parts array.

Return

BPAK_OK on success, -BPAK_FAILED if part_id already exists, -BPAK_NOT_FOUND if the part is missing

Parameters

[in] hdr: BPAK Header
[in] id: ID of part
[out] part: Output pointer to part

int bpak_add_part(struct bpak_header *hdr, uint32_t id, struct bpak_part_header **part)¶

Add new part with ‘id’. *ptr is assigned to a pointer within the hdr->parts array.

Return

BPAK_OK on success or -BPAK_NO_SPACE if the array is full

Parameters

[in] hdr: BPAK Header
[in] id: ID of new part
[out] part: Output pointer to new part

int bpak_valid_header(struct bpak_header *hdr)¶

Check magic numbers in the header and check that all parts have the correct alignment.

Return

BPAK_OK on success

Parameters

[in] hdr: BPAK Header

int bpak_copyz_signature(struct bpak_header *hdr, uint8_t *signature, size_t *size)¶

Copy the signature to ‘*signature’ and zero out the signature area in the header.

Signature size is returned in ‘*size’

Return

BPAK_OK On success

Parameters

[in] hdr: BPAK Header
[out] signature: Signature output buffer
[in] size: Size in and size out

int bpak_init_header(struct bpak_header *hdr)¶

Initialize empty header structure

Return

BPAK_OK on success

Parameters

[in] hdr: BPAK Header

uint64_t bpak_part_offset(struct bpak_header *hdr, struct bpak_part_header *part)¶

Get data offset of ‘part’ within the BPAK stream

Return

Offset in bytes

Parameters

[in] hdr: BPAK Header
[in] part: BPAK Part pointer

uint64_t bpak_part_size(struct bpak_part_header *part)¶

Get size of ‘part’

Return

Data size + padding bytes or transport size without padding depending on if the transport bit is set in part->flags

Parameters

[in] part: BPAK Part

const char *bpak_error_string(int code)¶

Translate error codes to string representation

Return

Textual representation of error code

Parameters

[in] code: Input error code

const char *bpak_known_id(uint32_t id)¶

Return string representaion of known id’s

Return

Textual representation of BPAK ID

Parameters

[in] id: BPAK ID

const char *bpak_signature_kind(uint8_t signature_kind)

Translates signature type to a textual version

Return

Textual version of signature kind

Parameters

[in] signature_kind: Signature kind

const char *bpak_hash_kind(uint8_t hash_kind)

Translate hash kind to a textual version

Return

Textual version of hash kind

Parameters

[in] hash_kind: Hash kind

int bpak_printf(int verbosity, const char *fmt, ...)¶

Prototype for bpak core library debug call

Return

BPAK_OK on success

Parameters

[in] verbosity: Verbosity level 0 to 2

const char *bpak_version(void)¶

Library version

Return: Library version as a text string

struct bpak_transport_meta¶

#include <bpak.h>

Transport mode meta data

Size: 32 bytes

Public Members

uint32_t alg_id_encode¶: Algorithm encoder ID

uint32_t alg_id_decode¶: Algorithm decoder ID

uint8_t data[24]¶: Algorithm specific data

struct bpak_part_header¶

#include <bpak.h>

BPAK part header

Size:32 byte

Public Members

uint32_t id¶: Part identifier

uint64_t size¶: Data block size

uint64_t offset¶: Offset in data stream

uint64_t transport_size¶: Should be populated when part data is prepared for transport. With the encoded size

uint16_t pad_bytes¶: Part padding up to the next 128 byte boundary

uint8_t flags¶: Flags

uint8_t pad¶: Pad to 32 bytes, set to zero

struct bpak_meta_header¶

#include <bpak.h>

BPAK Meta data header

Size: 16 byte

Public Members

uint32_t id¶: Metadata identifier

uint16_t size¶: Size of metadata

uint16_t offset¶: Offset in ‘metadata’ byte array

uint32_t part_id_ref¶: Optional reference to a part id

uint8_t pad[4]¶: Pad to 16 bytes

struct bpak_header¶

#include <bpak.h>

BPAK Header

Size: 4 kBytes

Public Members

uint32_t magic¶: BPAK Magic number

uint8_t pad0[4]¶: Pad 1

struct bpak_meta_header meta[BPAK_MAX_META]¶: Meta data header array

struct bpak_part_header parts[BPAK_MAX_PARTS]¶: Part header array

uint8_t metadata[BPAK_METADATA_BYTES]¶: Meta data byte array

uint8_t hash_kind¶: Hash kind used in package

uint8_t signature_kind¶: Signature kind used in package

uint16_t alignment¶: Alignment

uint8_t payload_hash[64]¶: Payload hash

uint32_t key_id¶: Signing key identifier

uint32_t keystore_id¶: Keystore identifier

uint8_t pad1[42]¶: Pad 2

uint8_t signature[BPAK_SIGNATURE_MAX_BYTES]¶: Signature data

uint16_t signature_sz¶: Signature size

bpak_core — BPAK Core library¶

`bpak_core` — BPAK Core library¶