Skip to contentSkip to conversation

binman: x509_cert: add PKCS#11/HSM signing support

PATCH Superseded Sergio Prado 2 participants 3 messages Apr 21 – Apr 25 Kbuild

v2 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

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
index dfc95d314ddd..8d6c584b2731 100644
@@ -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
index 3f725868c8bb..ea91199b1e22 100644
@@ -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
Reviewed-by on v2 1/1
#1 lore raw

Hi Sergio,

Quoted 31 lines · Sergio Prado

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>
[...]

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

#2 lore raw

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 support

Allow 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 if pkcs11_module is 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_URI is passed as the key argument.

Missed that. Thanks for pointing that out.

I will prepare and send v3.

Best regards,

Sergio Prado