1.36. barebox TLV - Non-Volatile Factory Data Storage¶
barebox TLV (“Tag Length Value” format) is a system to store and
retrieve a device’s (read-only) meta-data from non-volatile memory.
It is intended to handle information that are usually only set in
the factory - like serial number, MAC-addresses, analog calibration
data, etc.
Data is stored in a tag-length-value format (hence the name) and read
from non-volatile memory during startup.
Unpacked values are stored in the devicetree chosen-node.
barebox TLV consists of two components:
The parser inside barebox (
common/tlv). This code parses the non-volatile memory during startup.A Python-Tool (
scripts/bareboxtlv-generator). This script is intended to generate the TLV binaries in the factory.
1.36.1. Data Format¶
The TLV binary has the following format:
struct tlv {
be16 tag;
be16 len;
u8 payload[];
};
struct sig {
u8 spki_hash_prefix[4];
u8 signature[];
};
struct tlv_format {
be32 magic;
be32 length_tlv; /* in bytes */
be16 reserved; /* must be 0 */
be16 length_sig; /* in bytes */
struct tlv tlvs[];
struct sig signature; /* omitted if length_sig == 0 */
be32 crc;
};
1.36.3. Signature¶
If length_sig is zero, signature is disabled. The signature section of
the file is exactly length_sig bytes long. This includes the
spki_hash_prefix, followed by the signature itself. spki_hash_prefix
is the first four bytes of the sha256 hash of the Subject Public Key Info and
its purpose is to allow for quicker matching of a signed TLV with its
corresponding public key during signature verification.
The signature shall be verified on all fields before the signature field,
but with length_sig overwritten with 0,
hashed with sha256
and signed using any of the supported algorithms (currently RSA and some ECDSA curves).
Note that ECDSA signatures are not DER encoded but rather plain concatenation of r and s (each extended to the size of the ECDSA-key).
1.36.4. Data Types¶
barebox defines a number of common data types.
These are defined in common/tlv/barebox.c.
Board-specific extensions can add additional data types as needed.
1.36.5. TLV Binary Generation¶
To generate a TLV binary the schema for the specific TLV must be defined. Schemas are yaml-files that represent what the actual parser in barebox expects.
An example schema can be found in scripts/bareboxtlv-generator/schema-example.yaml.
This schema defines some well-known tags and two board-specific tags.
Afterwards another yaml-file with the data for the TLV binary is needed.
An example can be found in scripts/bareboxtlv-generator/data-example.yaml.
With these information in place a TLV binary can be created:
./bareboxtlv-generator.py --input-data data-example.yaml \
schema-example.yaml tlv.bin
To additionally sign the TLV, supply a private key using the --sign KEY option.
As bareboxtlv-generator.py internally uses openssl pkeyutl for
accessing the private key, when using OpenSSL 3, any provider, such as pkcs11,
that is correctly configured, can be used as KEY.
Note
- The
FactoryDatasetclass inbareboxtlv-generator.py is intended to be used as a library.
1.36.6. Data Location¶
The generated tlv.bin file has to be stored on the device in a known location.
This location can for example be described inside the devicetree of the device.
&eeprom1 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
tlv_partition: partition@0 {
compatible = "barebox,tlv-v1";
label = "barebox_tlv";
reg = <0x0 0x1000>;
};
};
};
The compatible defines the format to parse the TLV data as and the reg
describes the size of the data.
1.36.7. Custom TLV format¶
A custom TLV format can be created for example like this:
1 #include <string.h>
2 #include <tlv/tlv.h>
3 #include <common.h>
4
5 #define TLV_MAGIC_CUSTOM_V1_SIGNED 0xe3573cd3
6
7 static struct tlv_mapping custom_tlv_v1_mappings[] = {
8 /* UNIX timestamp of fabrication */
9 { 0x0003, tlv_format_timestamp, "factory-timestamp" },
10 /* Device serial number string */
11 { 0x0004, tlv_handle_serial, "device-serial-number" },
12 /* a comma separated list of features */
13 { 0x0006, tlv_format_str, "featureset" },
14 /* Printed Circuit Board Assembly serial number string */
15 { 0x0007, tlv_format_str, "pcba-serial-number" },
16 /* Reject TLV if supplied binary data does not match UID SoC register */
17 { 0x0024, tlv_bind_soc_uid, "bound-soc-uid" },
18 /* Custom key */
19 { 0x8001, tlv_format_str, "custom-key"},
20 { /* sentintel */ },
21 };
22
23 static struct tlv_mapping *mappings[] = {
24 custom_tlv_v1_mappings,
25 NULL
26 };
27
28 static struct of_device_id matches[] = {
29 { .compatible = "custom,tlv-v1" },
30 { /* sentinel */ }
31 };
32
33 static struct tlv_decoder custom_tlv_v1 = {
34 .magic = TLV_MAGIC_CUSTOM_V1_SIGNED,
35 .driver.name = "custom-tlv-v1",
36 .driver.of_compatible = matches,
37 .mappings = mappings,
38 .signature_keyring = "tlv-custom",
39 };
40
41 static int custom_tlv_v1_register(void)
42 {
43 return tlv_register_decoder(&custom_tlv_v1);
44 }
45 of_populate_initcall(custom_tlv_v1_register);
line 7-21: Every possible mapping, that is used must be listed here.
line 19: The mapping includes a custom tag. All tags above
0x8000are reserved for custom use.line 29: The compatible string of the partition, that will contain the data.
line 5,34: Some randomly generated 32bit value to uniquely identify the mapping-table.
line 38: The keyring tlv-stange should be used to validate the signature. Keys for the keyring are specified in the barebox config
CONFIG_CRYPTO_PUBLIC_KEYSwith for example:keyring=tlv-custom:__ENV__TLV_KEY.line 41-45: Registers the format into barebox.
