Looking for custom tlv documentation

[Olstyle]

I am trying to add additional data to my images, which should be used as an additional information about whether the image should be booted or not (one hardware with one bootloader becoming different devices later in the production process). So the data should be combined with the image and needs to be signed as part of the image.
Looking at the current documentation of imgtool, this looks just like what I need:

--custom-tlv [tag] [value]      Custom TLV that will be placed into
                                  protected area. Add "0x" prefix if the value
                                  should be interpreted as an integer,
                                  otherwise it will be interpreted as a
                                  string. Specify the option multiple times to
                                  add multiple TLVs.

But which tags are actually free to use?
Or don't they overlap with standard tlv entries?
And which interfaces should be used to access such a tlv?

@michalek-no maybe you can shed some light on this since it looks like you added the info about that option recently. So I guess you worked with it as well?

[taltenbach]

The list of the TLV types used by MCUboot can be found in image.h. In that header, there are areas defined for vendor-specific types:

mcuboot/boot/bootutil/include/bootutil/image.h

Lines 134 to 143 in 6cbea0a

	/*
	* vendor reserved TLVs at xxA0-xxFF,
	* where xx denotes the upper byte
	* range. Examples:
	* 0x00a0 - 0x00ff
	* 0x01a0 - 0x01ff
	* 0x02a0 - 0x02ff
	* ...
	* 0xffa0 - 0xfffe
	*/

The API for iterating over the TLVs of an image can be found at the end of the same header.

[sjlongland]

Silly question related to this. I'm trying to implement boot_retrieve_public_key_hash and need to know what "whitelisted" SHA-256 hash of maybe two or three possible permitted key hashes to serve up to permit an image to be validated.

I've set TLV 0x00a0 based on that list, to the "name" of a public key, somewhere in my flash memory, I'm keeping an array of these at a fixed address:

NN NN NN NN NN NN NN NN : 8 bytes key "name"
HH HH HH HH HH HH HH HH :
HH HH HH HH HH HH HH HH : SHA-256 hash
HH HH HH HH HH HH HH HH : of whitelisted
HH HH HH HH HH HH HH HH : key

I'm inside boot_retrieve_public_key_hash (MCUBOOT_HW_KEYS is enabled) and I want to read some custom TLVs to know which public key hash I should be looking at. I need to read TLV 0x00a0, then iterate over my flash partition doing strncmps on the names until we get a match, then memcpy the relevant hash.

flash_area_id_from_image_slot tells me which flash area ID I need to look at, and the Zephyr flash_area_open lets me access it. Great.

bootutil_tlv_iter_begin lets me begin iteration, but it expects a const struct image_header *hdr to be passed in. Presumably I have to allocate one and read the header in, but aside from some functions in a private header file, I see no method to do that.

How does one read a custom TLV?

[Olstyle]

Considering your actual task I would consider to look into this small PR which unfortunately went stale
#1869
That way you wouldn't need to scan the TLVS at all.

For the problem here I iterated roughly like this:

#define IMAGE_TLV_DEV_TYPE 0x00a0
int boot_perform_update_hook(int img_index, struct image_header *img_head,
                             const struct flash_area *area)
{
     uint8_t DeviceID[DEV_ID_SIZE];

    struct image_tlv_iter Iterator = {0};
    int RetCode;
    uint32_t Offset = 0;
    uint16_t Length = 0;

    //build iterator to look for device type TLV in secured TLV area
    RetCode = bootutil_tlv_iter_begin(&Iterator, img_head, area, IMAGE_TLV_DEV_TYPE, true);

    while(RetCode == 0)
    {
        /* Traverse through the protected TLV area to find
         * the TLV.
         */
        RetCode = bootutil_tlv_iter_next(&Iterator, &Offset, &Length, NULL);
        if (RetCode == 0)
        {
               //read the actual TLV
               RetCode = flash_area_read(area, Offset, DeviceID, Length);

boot_perform_update_hook(), which is activated with MCUBOOT_IMAGE_ACCESS_HOOKS is the trick to get to the pointers.
If you return something which is not BOOT_HOOK_REGULAR and not zero, you can also directly stop the update at that point if your whitelist check results to that.
Depending on when you want to jump into the logic, boot_read_image_header_hook could also be a usefull entry point.

[sjlongland]

It would solve this immediate use case, but not others where I might want or need to read TLV data, so I think a "fuller" solution is still warranted.

It's worth noting they could memcpy the expected key hash to the buffer they pass to the function and enable the routine to check it (or pass -1 if it's not kosher) without breaking the API they're concerned about.

I'll have a closer look at the function you've got there, but one issue I have is that I don't actually have a pointer to struct image_header *img_head, and that is actually the blocker. Use of the iterator looks simple enough, but I need the header pointer to use it.

[Olstyle]

None of the hooks I mentioned work for you?

[sjlongland]

Not sure I've got access to override those from Zephyr, and even if I did, I still have the problem of getting the pointer into boot_retrieve_public_key_hash and knowing whether that call relates to the previous call to boot_perform_update_hook.

But, as I say, there are other use cases where being able to read the TLVs in an image would be useful.

[sjlongland]

For those who are wondering how this is done, I actually took matters into my own hands and tried doing it myself.

I may have to do this because my application will likely be keeping firmware images in LittleFS, then when an OTA update is to be performed, it'll copy one of those images to the slot1 partition and do a reboot, so I need a way to read TLVs (and ultimately, verify) an image that's not stored in either slot0 or slot1.

I coded up a simple Python script that demonstrates what's needed:
mcuboot.py

Zephyr gives you an Intel hex file in build/app/zephyr/zephyr.signed.hex, this script though needs a raw binary so objcopy must be used to convert the format:

objcopy -Iihex -Obinary build/app/zephyr/zephyr.signed.hex /tmp/zephyr-signed.bin

I've got an image with some custom TLVs here, when I run my script I get output like the following:

$ python3 mcuboot.py /tmp/zephyr-signed.bin 
ImageHeader(ih_magic=2532554813, ih_load_addr=0, ih_hdr_size=4096, ih_protect_tlv_size=80, ih_img_size=745152, ih_flags=0, iv_major=1, iv_minor=8, iv_revision=18, iv_build_num=0, ih_pad1=0)
PTLV  0: 0x00a0 524f4f542d45432d50323536
PTLV  1: 0x00a1 524f4f542d45432d5032353600000000e30466f6b8470c1f29070b17f1e2d3e94d445e3f608087fdc711e4382bb538b6
PTLV  2: 0x00a2 02120801
UTLV  0: 0x0010 5b3fd950fbccfbf3ccbe709bc373af7e7d4b29bf59ec3cb322d3b9a56fb46227
UTLV  1: 0x0002 3059301306072a8648ce3d020106082a8648ce3d030107034200042acb403ce8feed5ba44995a1a91daee8dbbe1937cd14fb2f245737e5953988d994b9d65aebd7cdd5308ad6fe48b24a6a810ee5f07d8b6834cc3a6afc538efac1
UTLV  2: 0x0022 30440220080ed1cd85db15717d6082de70a355c4ad483ab5003e97963b967fff6398483d02204215eee9fd3249cf43dd7e89710c17f308851b10d802023e12633cea52ff6b3c

How does this get done in C? I haven't written that yet, but a rough guide on what needs to happen:

Firmware image layout

         +0              +8              +16
         ├─┴─┴─┴─┼─┴─┴─┴─┼─┴─┼─┴─┼─┴─┴─┴─┤ ← mcuboot header (32 bytes)
0x000000 │ Magic │ LAddr │HSz│PSz│ ImgSz │
         ├───────┼─┬─┬───┼───┴───┼───────┤
0x000010 │ Flags │M│I│REV│BuildNo│  Pad  │
         ├───────┴─┴─┴───┴───────┴───────┤
         ┆                               ┆
         ┆    Unused header padding      ┆
         ┆                               ┆
HSz    → ├───────────────────────────────┤ Header size (HSz) gives size of
         ┆                               ┆ the header in bytes and thus the
         ┆       Application code        ┆ position of the executable image.
         ┆           and data.           ┆
         ┆                               ┆
HSz    → ├───────────────┬───────────────┤
+ ImgSz  │  PTLV Header  │               │ 0 or more protected TLVs follow
         ├───────────────┘               ┆ the application/data partition.
         ┆        Protected TLVs         ┆
         ┆                               ┆
         ┆                               ┆
         ├───────────────┬───────────────┤
HSz    → │  UTLV Header  │               │ Unprotected TLVs follow the protected
+ ImgSz  ├───────────────┘               ┆ TLVs.  Metadata values like the
+ PSz    │       Unprotected TLVs        ┆ SHA-256, public key and digital
         ┆                               ┆ signature are placed here by mcuboot.
         ┆                               ┆
         └───────────────────────────────┘

All data from the beginning of the image up to the unprotected TLV header is
hashed using SHA-256 and this gets stored as an "unprotected TLV" known in
MCUBoot sources as IMAGE_TLV_SHA256 (value 0x0010).

For single-image projects, we verify the image and protected TLVs, we hash
from the beginning of the image (magic number) to the start of the unprotected
TLV region (ih_hdr_size + ih_protect_tlv_size + ih_img_size). (In split images,
there's an added complication of a seed hash. I have not investigated this.)

That hash is then digitally signed with a ECDSA key, the result of which is
stored in a separate unprotected TLV, IMAGE_TLV_ECDSA_SIG (value 0x0022).

Reading TLVs

To read TLVs, there are some functions in mcuboot's bootutil library,
however there are three glaring omissions:

1. the routines assume the image being read is stored in a flash area
   (and not, for example, in a LittleFS filesystem)
2. the routines therefore assume you've opened the appropriate flash area
   and obtained a pointer to it (they're nice enough to provide a function
   that tells you which partition ID corresponds to what image, but the rest
   is up to you)
3. no routine is provided that will read the header for you, that is a manual
   task you must undertake yourself.

Consequently, we've had to go the "Not Invented Here" route and re-invent
their wheel.

The following is a description of the process for reading an image. Note
that all fields are stored in little-endian format.

The first 32 bytes of the image binary is the MCUBoot image header. This
is depicted in the above ASCII-art diagram, but a rough rundown of the key
headers (in order):

• ih_magic (a uint32_t): A magic number that identifies the image as
  being a MCUBoot image. Possible values:
  • IMAGE_MAGIC (0x96F3B83D): MCUBoot v2
  • IMAGE_MAGIC_V1 (0x96F3B83C): MCUBoot v1 -- not compatible with MCUBoot v2
  • IMAGE_MAGIC_NONE (0xFFFFFFFF): Empty partition indicator
• ih_load_addr (a uint32_t): Load address for the image
• ih_hdr_size (a uint16_t): Size of the header including padding
• ih_protect_tlv_size (a uint16_t): Size of the protected TLV block
• ih_img_size (a uint32_t): Size of the executable image payload
• ih_flags (a uint32_t): Bootloader flags register, a bitmap that
  is used to indicate the presence of encryption, flag non-bootable images,
  indicate images that must be copied to RAM or a fixed ROM location, or
  use compression.
• ih_ver (a struct): the version information on the image:
  • iv_major (a uint8_t): major version number
  • iv_minor (a uint8_t): minor version number
  • iv_revision (a uint16_t): revision number
  • iv_build_num (a uint32_t): build number
• _pad1 (a uint32_t) padding of the image to 32 bytes.

We must check that ih_magic is equal to IMAGE_MAGIC. That tells us
whether there's a valid image here or not. Once we see that, we can start
to look at the TLV regions.

Each region begins with a TLV Info header which has the following structure:

• it_magic (a uint16_t): a magic number indicating which TLV region
  we're looking at:
  • IMAGE_TLV_INFO_MAGIC (0x6907): Unprotected TLV region follows
  • IMAGE_TLV_PROT_INFO_MAGIC (0x6908): Protected TLV region follows
• it_tlv_tot (a uint16_t): the size of this TLV region including header.

We jump to offset ih_hdr_size + ih_img_size and read in the TLV Info
header at that offset (8 bytes). We inspect it_magic:

• If it's IMAGE_TLV_PROT_INFO_MAGIC, this is the start of the protected
  TLV region:

  • Sanity check: it_tlv_tot must match ih_protect_tlv_size in the
    image header!
  • Increment the offset by 4 bytes (the TLV info header size) and make
    a note of the location: this is where we need to start looking for
    protected TLVs
  • Increment the offset by it_tlv_tot - 4 and make a note of that
    offset: this is where our protected TLVs end and the unprotected
    TLVs begin.
  • We should now be at the unprotected TLV info header, read the header
    at that offset.

• If it's IMAGE_TLV_INFO_MAGIC, this is the start of the unprotected
  TLV region:

  • Sanity check: ih_protect_tlv_size must be 0!
  • Make a note that there is no protected TLV region.

At this point, we either know where the protected TLV region is, or know
there is no protected TLV region in this image (which we should not
encounter for valid images). The offset should now be pointing at the
TLV Info structure for the unprotected TLV region:

• Verify that it_magic is IMAGE_TLV_INFO_MAGIC, bail if it isn't!
• Increment the offset by 4 bytes (the TLV info header size) and make
  a note of the location: this is where we need to start looking for
  unprotected TLVs
• Increment the offset by it_tlv_tot - 4 and make a note of that
  offset: this is where our unprotected TLVs end.
• Verify that we are now at the end of the image.

We now know the address ranges of our TLV regions. To find a particular
TLV in a given region. The TLVs are concatenated together, each starts
with an 8-byte header:

• it_type (a uint16_t): the TLV type code
• it_len (a uint16_t): the length of the data stored in the TLV

1. Start at the start offset for the region (just beyond the information
   header)
2. Read the 4-byte TLV header at the current offset
3. Inspect it_type:
   • If it matches: your data starts at offset + 4 and ends at
     offset + it_len, bon appetit!
4. Increment offset by it_len
5. If offset is now at the end of your TLV region, bail here -- what
   you're looking for is not present.
6. Go to step 2.

---

So that's what I've found out by digging through the code today and trying a few experiments, and if your use case falls outside of what MCUBoot's APIs permit, that might get you a little further.

C implementations should probably include the image.h header defined in MCUBoot and use the same struct definitions to avoid gotchas. The above guide might help someone though who has a need to read this information in something other than C too.