`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_EXPORT¶

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_HASH_MAX_LENGTH¶

BPAK_CHUNK_BUFFER_LENGTH¶

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

bpak_get_meta_ptr(_hdr, __meta, _T)¶

Typedefs

typedef uint32_t bpak_id_t¶

Numerical ID representing different types of objects

Size: 4 bytes

typedef ssize_t (*bpak_io_t)(off_t offset, uint8_t *buffer, size_t length, void *user)¶

typedef void *(*bpak_calloc_t)(size_t, size_t)¶

typedef void (*bpak_free_t)(void*)¶

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¶

enumerator BPAK_NEEDS_MORE_DATA¶

enumerator BPAK_WRITE_ERROR¶

enumerator BPAK_DECOMPRESSOR_ERROR¶

enumerator BPAK_COMPRESSOR_ERROR¶

enumerator BPAK_PATCH_READ_ORIGIN_ERROR¶

enumerator BPAK_PATCH_WRITE_ERROR¶

enumerator BPAK_READ_ERROR¶

enumerator BPAK_BAD_MAGIC¶

enumerator BPAK_UNSUPPORTED_HASH_ALG¶

enumerator BPAK_BUFFER_TOO_SMALL¶

enumerator BPAK_FILE_NOT_FOUND¶

enumerator BPAK_KEY_DECODE¶

enumerator BPAK_VERIFY_FAIL¶

enumerator BPAK_SIGN_FAIL¶

enumerator BPAK_UNSUPPORTED_KEY¶

enumerator BPAK_BAD_ROOT_HASH¶

enumerator BPAK_BAD_PAYLOAD_HASH¶

enumerator BPAK_MISSING_META_DATA¶

enumerator BPAK_PACKAGE_UUID_MISMATCH¶

enumerator BPAK_UNSUPPORTED_COMPRESSION¶

enumerator BPAK_KEY_NOT_FOUND¶

enumerator BPAK_KEYSTORE_ID_MISMATCH¶

enumerator BPAK_EXISTS¶

enum bpak_compression¶

BPAK Compression methods

Values:

enumerator BPAK_COMPRESSION_NONE¶

enumerator BPAK_COMPRESSION_HS¶

enumerator BPAK_COMPRESSION_LZMA¶

enum bpak_key_kind¶

BPAK key types

Values:

enumerator BPAK_KEY_INVALID¶

enumerator BPAK_KEY_PUB_RSA4096¶

enumerator BPAK_KEY_PUB_PRIME256v1¶

enumerator BPAK_KEY_PUB_SECP384r1¶

enumerator BPAK_KEY_PUB_SECP521r1¶

enumerator BPAK_KEY_PRI_RSA4096¶

enumerator BPAK_KEY_PRI_PRIME256v1¶

enumerator BPAK_KEY_PRI_SECP384r1¶

enumerator BPAK_KEY_PRI_SECP521r1¶

Functions

int bpak_get_meta(struct bpak_header *hdr, bpak_id_t id, bpak_id_t part_id_ref, struct bpak_meta_header **meta)¶

Get pointer to metadata header with ‘id’ and a part reference id ‘part_id_ref’.

Parameters:

hdr – [in] BPAK Header
id – [in] Meta data identifier
part_id_ref – [in] Part reference identifier, or 0 for no reference
meta – [out] Pointer to the metadata header

Returns:

BPAK_OK on success -BPAK_NOT_FOUND if the metadata is missing

int bpak_get_meta_anyref(struct bpak_header *hdr, bpak_id_t id, struct bpak_meta_header **meta)¶

Get pointer to metadata header with ‘id’ and any part reference id

Parameters:

hdr – [in] BPAK Header
id – [in] Meta data identifier
meta – [out] Pointer to the metadata header

Returns:

BPAK_OK on success -BPAK_NOT_FOUND if the metadata is missing

int bpak_add_meta(struct bpak_header *hdr, bpak_id_t id, bpak_id_t part_ref_id, uint16_t size, struct bpak_meta_header **meta)¶

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

Parameters:

hdr – [in] BPAK Header
id – [in] ID of new metadata
part_ref_id – [in] Optional part reference to use for new metadata
size – [in] Size in bytes of new metadata
meta – [out] Pointer to the metadata header

Returns:

BPAK_OK on success, -BPAK_NO_SPACE if the metadata array is full or -BPAK_EXISTS if a metadata with the same ‘id’ and ‘part_ref_id’ already exists

void bpak_del_meta(struct bpak_header *hdr, struct bpak_meta_header *meta)¶

Remove metadata pointed to by ‘meta’.

Parameters:

hdr – [in] BPAK Header
meta – [in] Pointer to metadata header. Assumed to be within hdr->meta array

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

Retrieve pointer to part with id ‘id’.

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

Parameters:

hdr – [in] BPAK Header
id – [in] ID of part

Returns:

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

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

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

Parameters:

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

Returns:

BPAK_OK on success, -BPAK_NO_SPACE if the array is full -BPAK_EXISTS if a part with the same ‘id’ already exists

void bpak_del_part(struct bpak_header *hdr, struct bpak_part_header *part)¶

Remove part pointed to by ‘part’.

Parameters:

hdr – [in] BPAK Header
part – [in] Pointer to part header. Assumed to be within hdr->parts array

int bpak_valid_header(struct bpak_header *hdr)¶

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

Parameters:: hdr – [in] BPAK Header
Returns:: BPAK_OK on success

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’

Parameters:

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

Returns:

BPAK_OK On success

int bpak_init_header(struct bpak_header *hdr)¶

Initialize empty header structure

Parameters:: hdr – [in] BPAK Header
Returns:: BPAK_OK on success

off_t bpak_part_offset(struct bpak_header *h, struct bpak_part_header *part)¶

Get data offset of ‘part’ within the BPAK stream. This includes the header (4kByte).

Parameters:: part – [in] BPAK Part pointer
Returns:: Offset in bytes

size_t bpak_part_size(struct bpak_part_header *part)¶

Get size of ‘part’

Parameters:: part – [in] BPAK Part
Returns:: Data size + padding bytes or transport size without padding depending on if the transport bit is set in part->flags

size_t bpak_part_size_wo_pad(struct bpak_part_header *part)¶

Get size of ‘part’ without padding

Parameters:: part – [in] BPAK Part
Returns:: Data size bytes or transport size without padding depending on if the transport bit is set in part->flags

const char *bpak_error_string(int code)¶

Translate error codes to string representation

Parameters:: code – [in] Input error code
Returns:: Textual representation of error code

const char *bpak_signature_kind(uint8_t signature_kind)

Translates signature type to a textual version

Parameters:: signature_kind – [in] Signature kind
Returns:: Textual version of signature kind

const char *bpak_hash_kind(uint8_t hash_kind)

Translate hash kind to a textual version

Parameters:: hash_kind – [in] Hash kind
Returns:: Textual version of hash kind

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

Prototype for bpak core library debug call

Parameters:: verbosity – [in] Verbosity level 0 to 2
Returns:: BPAK_OK on success

int bpak_set_key_id(struct bpak_header *hdr, uint32_t key_id)¶

Sets key id which is used when verifying the package as a key hint to select the correct verification key.

Parameters:

hdr – [in] BPAK Header
key_id – [in] The key ID

Returns:

BPAK_OK on success

int bpak_set_keystore_id(struct bpak_header *hdr, uint32_t keystore_id)¶

Set keystore ID which is used when verifying the package. The key pointed to by the ‘key_id’ is expected to exist in a keystore with id keystore_id

Parameters:

hdr – [in] BPAK Header
keystore_id – [in] The keystore ID

Returns:

BPAK_OK on success

int bpak_add_transport_meta(struct bpak_header *header, bpak_id_t part_id, uint32_t encoder_id, uint32_t decoder_id)¶

Add transport meta data to the header. ‘encoder_id’ and ‘decoder_id’ specifies which encoders/decoders should be used when encoding or decoding part with id ‘part_id’.

Parameters:

header – [in] BPAK Header
part_id – [in] Id of part
encoder_id – [in] Encoder id
decoder_id – [in] Decoder id

Returns:

BPAK_OK on success

const char *bpak_version(void)¶

Library version

Returns:: Library version as a text string

int bpak_set_calloc_free(bpak_calloc_t calloc_func, bpak_free_t free_func)¶

Override the default allocator

Parameters:

calloc_func – [in] Override calloc
free_func – [in] Ovverride free

Returns:

BPAK_OK on success,

void *bpak_calloc(size_t nmemb, size_t size)¶: Memory allocation wrapper

void bpak_free(void *ptr)¶: Memory allocation wrapper

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

bpak_id_t id¶: Part identifier

uint64_t size¶: Data block size

uint64_t offset¶: Offset in data decoded 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

bpak_id_t id¶: Metadata identifier

uint16_t size¶: Size of metadata

uint16_t offset¶: Offset in ‘metadata’ byte array

bpak_id_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¶