Introduce new wolfboot image inspection scripts

[gojimmypi]

wolfBoot image peek

While working on #614, I needed a tool to objectively validate a wolfboot-signed image.

Enclosed are new tools/scripts:

• wolfboot-der-to-spki.py - Convert wolfBoot raw/public-key container to standard SPKI DER;

This is a helper needed for image-peek.py - see below.

wolfboot-der-to-spki.py keystore.der [ --curve p256 | p384 | p521 ]

• image-peek.py - peek at a wolfBoot-signed image and display various diagnostic details

image-peek.py [-h] [--header-size HEADER_SIZE] [--dump-payload OUT] [--verify-hash] [--verify-sig PUBKEY] [--alg {ecdsa-p256,ed25519}] image

Example:

$ ./tools/scripts/wolfboot-der-to-spki.py ./keystore.der
Wrote: /mnt/c/workspace/wolfboot-gojimmypi/keystore_spki.der
Wrote: /mnt/c/workspace/wolfboot-gojimmypi/keystore_spki.pem
SPKI SHA-256 (hex): eebfe458d5bd85bbdb009b86fa9dca2ed406703f78077cb7691311ddec3e6646

$ ./tools/scripts/image-peek.py ./test_v1_signed.bin --verify-sig ./keystore_spki.der --alg ecdsa-p256
Magic: WOLF (raw: 574f4c46)
Payload size: 5 (0x00000005)
Header size: 256 (0x100)
Version: 1
Timestamp: 1761849639 (2025-10-30 18:40:39 UTC)
Hash (32 bytes): 2d2c2726a20552d58fd4811b0b0f7756176c914613218b2f84edc96006f7feda
Pubkey hint: 7327854161fa083b9dc144f652fc5360b0aaf809275a2e4d9bf8c4bedb6f1930
Signature (64 bytes): 17255f8a383d89b5...f58c760716d68969
[SIG] Signature OK (ECDSA) (alg=ecdsa-p256)

test-lib

This is in addition to the test-lib app, problematic validation shown here for reference:

#!/bin/bash

cp config/examples/library.config .config
make clean
make keysclean
make -C tools/keytools clean

# This script generates a target.h file
if [ -f "include/target.h" ]; then
    echo "Found existing target.h, removing it"
    rm -f include/target.h
fi

ASYM=ecc256
HASH=sha256


# ok:
# MATH="SPMATH=0 SPMATHALL=0 WOLFBOOT_SMALL_STACK=1"
MATH="SPMATH=1 WOLFBOOT_SMALL_STACK=0"

# Fail:
# MATH="SPMATH=1 WOLFBOOT_SMALL_STACK=1"

export MAKE_SIGN="${ASYM^^}"
export MAKE_HASH="${HASH^^}"

make -j1 keytools SIGN=${MAKE_SIGN} HASH=${MAKE_HASH}

echo "Generate a new keystore"
./tools/keytools/keygen --${ASYM} -g wolfboot_signing_private_key.der

echo ""
echo "Looking for test.bin to sign ..."
if [ -f "test.bin" ]; then
    echo "Found existing test.bin"
else
    echo "Creating a new test.bin"
    echo "Test" > test.bin
fi

echo ""
echo "Generate sign test.bin"
./tools/keytools/sign --${ASYM} --${HASH} test.bin wolfboot_signing_private_key.der 1

echo ""
echo "Make test-lib"
make -j1 "test-lib" SIGN=${MAKE_SIGN} HASH=${MAKE_HASH} ${MATH}
if [ -f "include/target.h" ]; then
    echo "Found new include/target.h after make test-lib"
else
    echo "WARNING: Expected to find a new include/target.h after make test-lib"
fi

echo ""
echo "Run ./test-lib test_v1_signed.bin"
./test-lib test_v1_signed.bin

See also my new VS2022 wolfBootTestLib.vcxproj validation app: in my tools/keytools. (PR soon)

Spoiler:

Root cause of at least one of my validation failures was the wrong user_settings.h:

./tools/keytools/user_settings.h vs ./include/user_settings.h

[danielinux]

This seems a good idea.

• Is there any plan to cover more hash / public key algorithms in image_peek.py?
• The wolfboot-der-to-spki.py tool could have a better name hinting at ECC, since it only covers ECC.

[gojimmypi]

Is there any plan to cover more hash / public key algorithms in image_peek.py?

Yes, definitely, in future PR as needed & time permits

The wolfboot-der-to-spki.py tool could have a better name hinting at ECC, since it only covers ECC.

Good point. Renamed

[dgarske]

I'd prefer a --read option for the tools/keygen/sign tool, but this is nice too.
Did you notice a read .py script that does something similar?
https://github.com/wolfSSL/wolfBoot/blob/master/tools/scripts/boot_status.py
Anyway to expand that?

[dgarske]

The name of this script needs changed. keystore to der?

[dgarske]

keystore.der is in root, not tools/keytools

[dgarske]

@aidangarske would you mind taking over this PR and fixing up the feedback? These are handy python script.

[gojimmypi]

I can continue to work on this if you'd like. Been distracted with other projects. Either is fine with me.

[dgarske]

I can continue to work on this if you'd like. Been distracted with other projects. Either is fine with me.

That's okay. Thanks for the offer. Merry Christmas Jim.

[aidangarske]

Closing in favor of #656, Thank you