binman: x509_cert: add PKCS#11/HSM signing support
PATCH v2 1/1 binman: x509_cert: add PKCS#11/HSM signing support
Allow X509 certificates used for K3/TI secure boot to be signed via an HSM using the PKCS#11 standard.
Two new make variables are introduced:
- BINMAN_PKCS11_URI PKCS#11 URI identifying the signing key on the HSM
- BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so)
When BINMAN_PKCS11_URI is set, it is passed to binman as the pkcs11-uri entry argument, which overrides the keyfile property at signing time.
The openssl bintool gains three helper methods:
- _pkcs11_use_provider() detects whether the pkcs11 provider (OpenSSL
Quoted 1 line
= 3.1) or the legacy pkcs11 engine (libp11) is available.
- _build_key_args() builds the appropriate -key/-provider/-engine arguments for the openssl command line, appending ?pin-value=<pin> from the PKCS11_PIN environment variable when set.
- _run_cmd_pkcs11() exports PKCS11_MODULE_PATH and PKCS11_PROVIDER_MODULE before invoking openssl when a module path is provided.
Existing behavior is unchanged when neither BINMAN_PKCS11_URI nor BINMAN_PKCS11_MODULE is set.
Tested with SoftHSM2 and a Yubikey using the verdin-am62_a53_defconfig configuration.
---
Changes in v2:
- Add tests for _build_key_args() (PEM path, PKCS#11 provider, PKCS#11 engine, PIN appending), _pkcs11_use_provider() (caching), _run_cmd_pkcs11() (with and without module path), and end-to-end x509_cert signing with a PKCS#11 URI (testX509CertPkcs11), making sure btool/openssl.py and etype/x509_cert.py has 100% test coverage.
Makefile | 2 + tools/binman/binman.rst | 18 ++++++ tools/binman/btool/openssl.py | 106 +++++++++++++++++++++++++++----- tools/binman/etype/x509_cert.py | 47 ++++++++++++-- tools/binman/ftest.py | 96 +++++++++++++++++++++++++++++ 5 files changed, 249 insertions(+), 20 deletions(-)
Makefile +2 -0
@@ -1701,6 +1701,8 @@ cmd_binman = $(srctree)/tools/binman/binman $(if $(BINMAN_DEBUG),-D) \ -a vpl-dtb=$(CONFIG_VPL_OF_REAL) \ -a pre-load-key-path=${PRE_LOAD_KEY_PATH} \ -a of-spl-remove-props=$(CONFIG_OF_SPL_REMOVE_PROPS) \ + $(if $(BINMAN_PKCS11_URI),-a pkcs11-uri="$(BINMAN_PKCS11_URI)") \ + $(if $(BINMAN_PKCS11_MODULE),-a pkcs11-module="$(BINMAN_PKCS11_MODULE)") \ $(BINMAN_$(@F)) OBJCOPYFLAGS_u-boot.ldr.hex := -I binary -O ihex
tools/binman/binman.rst +18 -0
@@ -2165,6 +2165,24 @@ BINMAN_INDIRS Sets the search path for input files used by binman by adding one or more `-I` arguments. See :ref:`External blobs`. +BINMAN_PKCS11_URI + PKCS#11 URI used to sign boot artifacts via an HSM instead of a PEM key + file on disk. When set, it is passed as ``-a pkcs11-uri=<uri>`` to binman, + which overrides the ``keyfile`` entry argument for all signing operations. + Example:: + + make BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private" + +BINMAN_PKCS11_MODULE + Path to the PKCS#11 shared library (.so) for HSM signing. When set, it is + passed as ``-a pkcs11-module=<path>`` to binman. Only needed when the + module is not already configured via ``openssl.cnf`` or the + ``PKCS11_MODULE_PATH`` environment variable. Typically used together with + ``BINMAN_PKCS11_URI``:: + + make BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private" \ + BINMAN_PKCS11_MODULE="/usr/lib/pkcs11/libsofthsm2.so" + BINMAN_TOOLPATHS Sets the search path for external tool used by binman by adding one or more `--toolpath` arguments. See :ref:`External tools`.
tools/binman/btool/openssl.py +90 -16
204 lines not on this page · raw message
tools/binman/etype/x509_cert.py +43 -4
101 lines not on this page · raw message
tools/binman/ftest.py +96 -0
102 lines not on this page · raw message
Signature · 1 line
2.34.1
Hi Sergio,
Quoted 31 lines · Sergio Prado
binman:
x509_cert: add PKCS#11/HSM signing supportAllow X509 certificates used for K3/TI secure boot to be signed via an HSM using the PKCS#11 standard.
Two new make variables are introduced:
-
BINMAN_PKCS11_URIPKCS#11 URI identifying the signing key on the HSM
-BINMAN_PKCS11_MODULEPath to the PKCS#11 shared library (.so)When
BINMAN_PKCS11_URIis set, it is passed to binman as the pkcs11-uri entry argument, which overrides the keyfile property at signing time.The openssl bintool gains three helper methods:
-
_pkcs11_use_provider()detects whether the pkcs11 provider (OpenSSLQuoted 1 line
= 3.1) or the legacy pkcs11 engine (libp11) is available.
-
_build_key_args()builds the appropriate -key/-provider/-engine arguments for the openssl command line, appending ?pin-value=<pin>
[...]
Makefile| 2 +tools/binman/binman.rst | 18 +++++++ tools/binman/btool/openssl.py | 106 ++++++++++++++++++++++++++++++++++------ tools/binman/etype/x509_cert.py | 47 ++++++++++++++++-- tools/binman/ftest.py | 96 ++++++++++++++++++++++++++++++++++++ 5 files changed, 249 insertions(+), 20 deletions(-)
tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 39
Quoted 4 lines
tools/binman/btool/openssl.py +4
-0@@ -35,18 +36,83 @@ class Bintoolopenssl(bintool.Bintool): + if key_fname.startswith('pkcs11:'): + pin = os.environ.get('PKCS11_PIN') + if pin: + key_fname = f'{key_fname}?pin-value={pin}'
This assumes the URI has no existing query parameters. It might be worth using '&' instead of '?' if the URI already contains '?'
tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 40
Quoted 7 lines
tools/binman/btool/openssl.py +5
-0@@ -35,18 +36,83 @@ class Bintoolopenssl(bintool.Bintool): + def _run_cmd_pkcs11(self, pkcs11_module, *args): + if pkcs11_module: + os.environ['PKCS11_MODULE_PATH'] = pkcs11_module + os.environ['PKCS11_PROVIDER_MODULE'] = pkcs11_module + return self.run_cmd(*args)
Setting os.environ directly pollutes the global environment. This could cause issues if binman signs multiple images with different module paths in a single run. It would be cleaner to pass the env to run_cmd() explicitly. What do you think?
Also, the environment variables persist even if pkcs11_module is None on a subsequent call.
Quoted 8 lines
tools/binman/ftest.py +6
-0@@ -6884,6 +6884,102 @@ fdt fdtmap Extract the devicetree blob from the fdtmap + def testX509CertPkcs11(self): + """Test X509 certificate creation using a PKCS#11 URI instead of a key file""" + PKCS11_URI = 'pkcs11:token=test;object=mykey;type=private' + PKCS11_MODULE = '/usr/lib/pkcs11/libsofthsm2.so' + original = bintool.Bintool.run_cmd +
tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6899
Quoted 10 lines
tools/binman/ftest.py +10
-0+ def fake_openssl(self_tool, *args, binary=False): + if self_tool.name != 'openssl': + return original(self_tool, *args, binary=binary) + arg_list = list(args) + if arg_list == ['list', '-providers']: + return 'pkcs11 provider' + if '-out' in arg_list: + tools.write_file(arg_list[arg_list.index('-out') + 1], + b'\x00' * 32) + return ''
The test only confirms the code path runs without error. You could also add assertions that check the args contain '-provider pkcs11' and that PKCS11_URI is passed as the key argument.
Regards,
Simon
Hi Simon,
Thanks for reviewing,
Em ter., 21 de abr. de 2026 às 21:15, Simon Glass <[email protected]> escreveu:
Quoted 10 lines
Hi Sergio,
Review
Quoted 6 lines · Sergio Prado
binman:
x509_cert: add PKCS#11/HSM signing supportAllow X509 certificates used for K3/TI secure boot to be signed via an HSM using the PKCS#11 standard.
(quoted diff) +0
-0
b/tools/binman/btool/openssl.py
Quoted 8 lines
tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 39
Quoted 5 lines
tools/binman/btool/openssl.py +4
-0@@ -35,18 +36,83 @@ class Bintoolopenssl(bintool.Bintool): + if key_fname.startswith('pkcs11:'): + pin = os.environ.get('PKCS11_PIN') + if pin: + key_fname = f'{key_fname}?pin-value={pin}'This assumes the URI has no existing query parameters. It might be worth using '&' instead of '?' if the URI already contains '?'
Good catch. Will do, and also add a test for this.
Quoted 1 line
Review
Quoted 1 line
(quoted diff) +0
-0
b/tools/binman/btool/openssl.py
Quoted 5 lines
Quoted 5 lines
tools/binman/btool/openssl.py +4
-0@@ -35,18 +36,83 @@ class Bintoolopenssl(bintool.Bintool): + def _run_cmd_pkcs11(self, pkcs11_module, *args): + if pkcs11_module: + os.environ['PKCS11_MODULE_PATH'] = pkcs11_module + os.environ['PKCS11_PROVIDER_MODULE'] = pkcs11_module
Quoted 8 lines
tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 101
Quoted 1 line
tools/binman/btool/openssl.py +1
-0+ return self.run_cmd(*args)Setting os.environ directly pollutes the global environment. This could cause issues if binman signs multiple images with different module paths in a single run. It would be cleaner to pass the env to
run_cmd()explicitly. What do you think?
Also, the environment variables persist even ifpkcs11_moduleis None on a subsequent call.
Makes sense. I will add an extra_env dict to run_cmd_result and run_cmd in bintool.py to be merged into the subprocess environment for that invocation only.
Quoted 2 lines
tools/binman/ftest.py fdt fdtmap Extract the
Quoted 2 lines
tools/binman/ftest.py +0
-0@@ -6884,6 +6884,102 @@ fdt fdtmap Extract the
devicetree blob from the fdtmap
Quoted 2 lines
tools/binman/ftest.py fdt fdtmap Extract the · line 6885
Quoted 2 lines
tools/binman/ftest.py +2
-0+ def testX509CertPkcs11(self): + """Test X509 certificate creation using a PKCS#11 URI instead
of a key file"""
Quoted 15 lines
Quoted 4 lines
tools/binman/ftest.py +4
-0+ PKCS11_URI = 'pkcs11:token=test;object=mykey;type=private' + PKCS11_MODULE = '/usr/lib/pkcs11/libsofthsm2.so' + original = bintool.Bintool.run_cmd +tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6968
Quoted 10 lines
tools/binman/ftest.py +10
-0+ def fake_openssl(self_tool, *args, binary=False): + if self_tool.name != 'openssl': + return original(self_tool, *args, binary=binary) + arg_list = list(args) + if arg_list == ['list', '-providers']: + return 'pkcs11 provider' + if '-out' in arg_list: + tools.write_file(arg_list[arg_list.index('-out') + 1], + b'\x00' * 32) + return ''
Quoted 3 lines
The test only confirms the code path runs without error. You could also add assertions that check the args contain '-provider pkcs11' and that
PKCS11_URIis passed as the key argument.
Missed that. Thanks for pointing that out.
I will prepare and send v3.
Best regards,
Sergio Prado