Skip to contentSkip to conversation

binman: add PKCS#11/HSM signing support for X509 certificates

PATCH Superseded Sergio Prado 3 participants 17 messages Apr 25 – May 8 Kbuild

v3 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

v3 cover binman: add PKCS#11/HSM signing support for X509 certificates

Motivation
----------

TI K3 secure boot requires X509 certificates to be signed with a private key at build time. Until now, binman expected this key to be present as a plain PEM file on the build host. For production use, however, private keys should never exist unprotected on a build machine — they belong inside a Hardware Security Module (HSM) that enforces access control and keeps the key material unexportable.

This series adds support for signing X509 certificates via any PKCS#11- capable HSM (YubiKey, TPM, network HSM, SoftHSM2 for development, etc.).

Design
------

Two new make variables are the sole user-visible interface:

BINMAN_PKCS11_URI PKCS#11 URI of the signing key on the HSM, e.g.
pkcs11:token=mytoken;object=mykey;type=private
BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so), e.g.
/usr/lib/softhsm/libsofthsm2.so (optional when the module is already configured via openssl.cnf or PKCS11_MODULE_PATH)

When BINMAN_PKCS11_URI is set, binman replaces the on-disk keyfile with the URI at signing time. The PKCS11_PIN environment variable can be used to supply the token PIN non-interactively; it is appended as a pin-value=<pin> query parameter to the URI.

The openssl bintool auto-detects which OpenSSL PKCS#11 interface to use:

- If the pkcs11 provider is loaded (OpenSSL >= 3.1 + pkcs11-provider), it uses -provider default -provider pkcs11.
- Otherwise it falls back to the legacy libp11 engine (-engine pkcs11 -keyform engine).

Detection is done once via 'openssl list -providers' and the result is cached, so there is no per-signing subprocess overhead.

Testing
-------

Tested on a Toradex Verdin AM62 (verdin-am62_a53_defconfig) board with both legacy engine path and pkcs11 provider path using SoftHSM2 and YubiKey 5 NFC.

A subtle issue was discovered during testing: binman uses a ThreadPoolExecutor internally (etype/section.py) and may call multiple ObtainContents() methods concurrently even under make -j1. SoftHSM2 and some real HSMs do not support simultaneous logins from different threads, which caused intermittent "login failed" and "object not found" errors during multi-certificate builds. To fix it, a module-level threading.Lock was used to serialise all PKCS#11 signing calls.

Test coverage: btool/openssl.py and etype/x509_cert.py remain at 100% (verified with 'binman test -T').

Changes in v3:
- Split into two patches: bintool infrastructure (1/2) and x509_cert feature (2/2)
- Fix global environment mutation: _run_cmd_pkcs11() no longer writes to os.environ directly; it now uses the new extra_env parameter so module paths are scoped to the subprocess only, which is both cleaner and safe under concurrent execution
- Add module-level threading.Lock to serialise concurrent PKCS#11 signing calls and fix intermittent login failures caused by binman's ThreadPoolExecutor
- Fix URI query string separator: use '&' when the URI already contains '?' (e.g. module-path already present), '?' otherwise
- Test cases updated

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), ensuring btool/openssl.py and etype/x509_cert.py have 100% test coverage

Sergio Prado (2):
binman: bintool: add extra_env parameter to run_cmd
binman: x509_cert: add PKCS#11/HSM signing support

 Makefile                        |   2 +
 tools/binman/binman.rst         |  18 +++++
 tools/binman/bintool.py         |  15 +++-
 tools/binman/btool/openssl.py   | 117 +++++++++++++++++++++++++++-----
 tools/binman/etype/x509_cert.py |  47 +++++++++++--
 tools/binman/ftest.py           | 110 ++++++++++++++++++++++++++++++
 6 files changed, 286 insertions(+), 23 deletions(-)
Signature · 1 line
2.34.1
#1 lore raw

PATCH v3 1/2 binman: bintool: add extra_env parameter to run_cmd

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

---
 tools/binman/bintool.py | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)
tools/binman/bintool.py +12 -3
index 9c76c8881a46..9d4f31b8afa1 100644
@@ -272,7 +272,8 @@ class Bintool:
                 show_status(col.RED, 'Failures', status[FAIL])
         return not status[FAIL]
 
-    def run_cmd_result(self, *args, binary=False, raise_on_error=True):
+    def run_cmd_result(self, *args, binary=False, raise_on_error=True,
+                       extra_env=None):
         """Run the bintool using command-line arguments
 
         Args:
@@ -281,6 +282,8 @@ class Bintool:
             binary (bool): True to return output as bytes instead of str
             raise_on_error (bool): True to raise a ValueError exception if the
                 tool returns a non-zero return code
+            extra_env (dict): Extra environment variables to set for this
+                invocation, or None
 
         Returns:
             CommandResult: Resulting output from the bintool, or None if the
@@ -291,6 +294,10 @@ class Bintool:
         name = os.path.expanduser(self.name)  # Expand paths containing ~
         all_args = (name,) + args
         env = tools.get_env_with_path()
+        if extra_env:
+            if env is None:
+                env = dict(os.environ)
+            env.update(extra_env)
         tout.debug(f"bintool: {' '.join(all_args)}")
         result = command.run_pipe(
             [all_args], capture=True, capture_stderr=True, env=env,
@@ -315,18 +322,20 @@ class Bintool:
             tout.debug(result.stderr)
         return result
 
-    def run_cmd(self, *args, binary=False):
+    def run_cmd(self, *args, binary=False, extra_env=None):
         """Run the bintool using command-line arguments
 
         Args:
             args (list of str): Arguments to provide, in addition to the bintool
                 name
             binary (bool): True to return output as bytes instead of str
+            extra_env (dict): Extra environment variables to set for this
+                invocation, or None
 
         Returns:
             str or bytes: Resulting stdout from the bintool
         """
-        result = self.run_cmd_result(*args, binary=binary)
+        result = self.run_cmd_result(*args, binary=binary, extra_env=extra_env)
         if result:
             return result.stdout
 
Signature · 1 line
2.34.1
#2 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Sergio,

Quoted 10 lines · Sergio Prado

[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

Yeah, I'm not convinced this is useful.

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Just mock the environment with

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Cheers,
Quentin

#3 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Quentin,

Quoted 5 lines · Quentin Schulz

Yeah, I'm not convinced this is useful.

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Quoted 7 lines

Just mock the environment with

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Yes, that makes sense. It does add unnecessary complexity, especially if it requires
propagating state across multiple layers. I'll drop this commit and rework the approach.

Quoted 7 lines

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Agreed. I’ll align with that approach and move the OpenSSL/PKCS#11 configuration fully outside of binman, similar to what is done for FIT signing.

Quoted 4 lines

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Yes, I agree. Letting the user control this via their OpenSSL configuration is the cleanest approach.

One caveat is that the legacy engine-based flow (e.g. pkcs11 via libp11) does not integrate transparently with OpenSSL 3’s STORE path (e.g. -key pkcs11:...) and typically still requires explicit -engine/-keyform engine usage. I'll elaborate on this in my reply to the second patch, since it directly affects that part of the implementation.

Thanks for the feedback.

Cheers,

Sergio Prado

Em seg., 27 de abr. de 2026 às 06:48, Quentin Schulz < [email protected]> escreveu:

Quoted 5 lines

Hi Sergio,

Quoted 1 line · Sergio Prado

[You don't often get email from [email protected]. Learn why

this is important at https://aka.ms/LearnAboutSenderIdentification ]

Quoted 38 lines
Quoted 9 lines

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

Yeah, I'm not convinced this is useful.

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Just mock the environment with

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Cheers,
Quentin

#4 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

In reply to Quentin Schulz

Hi Quentin,

Quoted 17 lines · Quentin Schulz

Hi Sergio,

Quoted 10 lines · Sergio Prado

[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

Yeah, I'm not convinced this is useful.

Quoted 7 lines

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Just mock the environment with

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

While we can mock the environment, it becomes confusing as the mocks pile up. The code path in the test effectively differs from the actual code path, since the mock is overriding something that it assumes the underlying code does, so any changes can cause strange errors.

The normal approach with binman tests is to pass through the settings they want. See for example _DoTestFile()

If you look through the tests, there is almost no mocking despite the large amount of functionality provided by Binman.

Quoted 12 lines

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Quoted 4 lines

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Fair enough. I wonder how the tests deal with something which is externally configured, though?

Regards,
Simon

#5 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Simon,

Quoted 25 lines · Simon Glass

Hi Quentin,

Quoted 22 lines · Quentin Schulz

Hi Sergio,

Quoted 10 lines · Sergio Prado

[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

Yeah, I'm not convinced this is useful.

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Just mock the environment with

Quoted 8 lines
Quoted 2 lines

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

While we can mock the environment, it becomes confusing as the mocks pile up. The code path in the test effectively differs from the actual code path, since the mock is overriding something that it assumes the underlying code does, so any changes can cause strange errors.

Sorry, I don't understand what you meant here, can you rephrase?

Quoted 6 lines

The normal approach with binman tests is to pass through the settings they want. See for example _DoTestFile()

If you look through the tests, there is almost no mocking despite the large amount of functionality provided by Binman.

How many of those features are actually dependent on environment variables?

Here, configuring OpenSSL, SOFTHSM2, and OpenSSL providers, we clearly are in the same scenario as when doing FIT signing with OpenSSL engines.

Quoted 12 lines
Quoted 12 lines

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Quoted 8 lines
Quoted 4 lines

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Fair enough. I wonder how the tests deal with something which is externally configured, though?

You set the OPENSSL_CONF, OPENSSL_ENGINES and SOFTHSM2_CONF environment variables to point at files that are generated for the tests. See the various unittest.mock.patch.dict('os.environ',) in tools/binman/ftest.py and tools/binman/test/fit/openssl.conf as well as tools/binman/test/fit/softhsm2.conf.

Cheers,
Quentin

#6 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Quentin,

Quoted 32 lines · Quentin Schulz

Hi Simon,

Quoted 28 lines · Simon Glass

Hi Quentin,

Quoted 24 lines · Quentin Schulz

Hi Sergio,

Quoted 10 lines · Sergio Prado

[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]

Add an optional extra_env dict parameter to run_cmd() and run_cmd_result(). When provided, the key/value pairs are merged into the subprocess environment for that invocation only, leaving the parent process environment unchanged.

This might be needed by bintools that must inject environment variables into specific tool calls without polluting the global environment.

Yeah, I'm not convinced this is useful.

We would need to propagate this new variable to whatever calls those methods as well. And it quickly balloons.

Just mock the environment with

with unittest.mock.patch.dict('os.environ', {'MYVAR': 'myval'}): like in testFitSignPKCS11Object for example?

Quoted 7 lines
Quoted 5 lines

While we can mock the environment, it becomes confusing as the mocks pile up. The code path in the test effectively differs from the actual code path, since the mock is overriding something that it assumes the underlying code does, so any changes can cause strange errors.

Sorry, I don't understand what you meant here, can you rephrase?

Basically mocks are fragile since they assume certain behaviour of the implementation. Change that and the mocks break in confusing ways.

My understanding of the justification for NOT passing the env argument is that it is annoying to do that plumbing. But I would rather do that plumbing. Perhaps not stated, but one of Binman's design goals is to try to have callers pass in their requirements rather than relying on state or sideways data (although there is plenty of that even so :-)

Quoted 34 lines
Quoted 7 lines

The normal approach with binman tests is to pass through the settings they want. See for example _DoTestFile()

If you look through the tests, there is almost no mocking despite the large amount of functionality provided by Binman.

How many of those features are actually dependent on environment variables?

Here, configuring OpenSSL, SOFTHSM2, and OpenSSL providers, we clearly are in the same scenario as when doing FIT signing with OpenSSL engines.

Quoted 12 lines
Quoted 12 lines

I'm also very skeptical of the need for binman to *set* environment variables to setup openssl.

Look at what's been done for testFitSignPKCS11Object, we externally configure openssl and softhsm so that binman doesn't have to know about it. This avoids having to play smart and adding a bunch of new variables. Is it possible to implement something like that for the x509 certificates? For FIT, we do use fit,engine, fit,engine-keydir/key-name-hint with mkimage to (possibly) use pkcs11, custom openssl engines, etc..

Quoted 8 lines
Quoted 4 lines

Also, I don't think we should decide for the user whether they are forced to use a provider or an engine based on the presence of the provider? just let them configure openssl to use the one they want externally?

Fair enough. I wonder how the tests deal with something which is externally configured, though?

Quoted 5 lines

You set the OPENSSL_CONF, OPENSSL_ENGINES and SOFTHSM2_CONF environment variables to point at files that are generated for the tests. See the various unittest.mock.patch.dict('os.environ',) in tools/binman/ftest.py and tools/binman/test/fit/openssl.conf as well as tools/binman/test/fit/softhsm2.conf.

Right, so the tests determine / set up the environment and then test accordingly. That's fine. I'd just like to avoid mocks here.

Regards,
Simon

#7 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Simon,

Quoted 5 lines

My understanding of the justification for NOT passing the env argument is that it is annoying to do that plumbing. But I would rather do that plumbing. Perhaps not stated, but one of Binman's design goals is to try to have callers pass in their requirements rather than relying on state or sideways data (although there is plenty of that even so :-)

I came up with a solution similar to FIT image signing. It is much simpler and does not require passing additional environment variables to binman (though it still requires defining a few environment variables when invoking make, such as OPENSSL_CONF and SOFTHSM2_CONF, which I assume is what you referred to as “sideways data”).

Please let me know if I should submit this new version as v4, or is the approach of passing environment variables to binman still under discussion.

Thanks for reviewing.

Regards,

Sergio Prado

#8 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Hi Sergio,

Quoted 9 lines · Sergio Prado

Hi Simon,

Quoted 5 lines

My understanding of the justification for NOT passing the env argument is that it is annoying to do that plumbing. But I would rather do that plumbing. Perhaps not stated, but one of Binman's design goals is to try to have callers pass in their requirements rather than relying on state or sideways data (although there is plenty of that even so :-)

Quoted 3 lines

I came up with a solution similar to FIT image signing. It is much simpler and does not require passing additional environment variables to binman (though it still requires defining a few environment variables when invoking make, such as OPENSSL_CONF and SOFTHSM2_CONF, which I assume is what you referred to as “sideways data”).

Please let me know if I should submit this new version as v4, or is the approach of passing environment variables to binman still under discussion.

Let's see what Quentin thinks about this...

Quoted 2 lines

Thanks for reviewing.

Regards,
Simon

#9 lore raw

Re: [PATCH v3 1/2] binman: bintool: add extra_env parameter to run_cmd

Quoted 12 lines · Simon Glass

Hi Sergio,

Quoted 9 lines · Sergio Prado

Hi Simon,

Quoted 5 lines

My understanding of the justification for NOT passing the env argument is that it is annoying to do that plumbing. But I would rather do that plumbing. Perhaps not stated, but one of Binman's design goals is to try to have callers pass in their requirements rather than relying on state or sideways data (although there is plenty of that even so :-)

Quoted 6 lines
Quoted 3 lines

I came up with a solution similar to FIT image signing. It is much simpler and does not require passing additional environment variables to binman (though it still requires defining a few environment variables when invoking make, such as OPENSSL_CONF and SOFTHSM2_CONF, which I assume is what you referred to as “sideways data”).

Please let me know if I should submit this new version as v4, or is the approach of passing environment variables to binman still under discussion.

Let's see what Quentin thinks about this...

Please send the v4 so we can have a look at it but it sounds nice already :)

Cheers,
Quentin

#10 lore raw

PATCH v3 2/2 binman: x509_cert: add PKCS#11/HSM signing support

In reply to Sergio Prado

Allow X509 certificates used for TI K3 secure boot to be signed via an HSM using the PKCS#11 standard, so that the private key never leaves the hardware token.

Two new make variables are introduced:

BINMAN_PKCS11_URI PKCS#11 URI identifying the signing key, e.g.
pkcs11:token=mytoken;object=mykey;type=private
BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so), e.g.
/usr/lib/softhsm/libsofthsm2.so

When BINMAN_PKCS11_URI is set, it is forwarded to binman as the pkcs11-uri entry argument, overriding the keyfile property at signing time. BINMAN_PKCS11_MODULE is optional and only needed when the PKCS#11 library is not already configured via openssl.cnf or the PKCS11_MODULE_PATH environment variable.

The openssl bintool gains three helper methods:

_pkcs11_use_provider() auto-detects whether the OpenSSL pkcs11
provider (OpenSSL >= 3.1, pkcs11-provider) or the legacy pkcs11 engine (libp11) is available, by inspecting 'openssl list -providers'.

_build_key_args() builds the -key/-provider/-engine arguments for the
openssl command line. When PKCS11_PIN is set in the environment, its value is appended as ?pin-value=<pin> to the URI so that non-interactive signing works with both the provider and engine paths.

_run_cmd_pkcs11() sets PKCS11_MODULE_PATH and PKCS11_PROVIDER_MODULE
before invoking openssl when a module path is given, and serialises concurrent signing calls with a module-level lock. The lock is required because binman's ThreadPoolExecutor may invoke multiple signing operations simultaneously, and HSMs (including SoftHSM2) do not support concurrent logins from different threads.

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 and both engine and provider OpenSSL APIs.

---
 Makefile                        |   2 +
 tools/binman/binman.rst         |  18 +++++
 tools/binman/btool/openssl.py   | 117 +++++++++++++++++++++++++++-----
 tools/binman/etype/x509_cert.py |  47 +++++++++++--
 tools/binman/ftest.py           | 110 ++++++++++++++++++++++++++++++
 5 files changed, 274 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 366491089ad9..e60eb7f572eb 100644
@@ -2161,6 +2161,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 +101 -16

219 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 +110 -0

116 lines not on this page · raw message

Signature · 1 line
2.34.1
#11 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

Hi Sergio,

Quoted 81 lines · Sergio Prado

Allow X509 certificates used for TI K3 secure boot to be signed via an HSM using the PKCS#11 standard, so that the private key never leaves the hardware token.

Two new make variables are introduced:

BINMAN_PKCS11_URI PKCS#11 URI identifying the signing key, e.g.
pkcs11:token=mytoken;object=mykey;type=private
BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so), e.g.
/usr/lib/softhsm/libsofthsm2.so

When BINMAN_PKCS11_URI is set, it is forwarded to binman as the pkcs11-uri entry argument, overriding the keyfile property at signing time. BINMAN_PKCS11_MODULE is optional and only needed when the PKCS#11 library is not already configured via openssl.cnf or the PKCS11_MODULE_PATH environment variable.

The openssl bintool gains three helper methods:

_pkcs11_use_provider() auto-detects whether the OpenSSL pkcs11
provider (OpenSSL >= 3.1, pkcs11-provider) or the legacy pkcs11 engine (libp11) is available, by inspecting 'openssl list -providers'.

_build_key_args() builds the -key/-provider/-engine arguments for the
openssl command line. When PKCS11_PIN is set in the environment, its value is appended as ?pin-value=<pin> to the URI so that non-interactive signing works with both the provider and engine paths.

_run_cmd_pkcs11() sets PKCS11_MODULE_PATH and PKCS11_PROVIDER_MODULE
before invoking openssl when a module path is given, and serialises concurrent signing calls with a module-level lock. The lock is required because binman's ThreadPoolExecutor may invoke multiple signing operations simultaneously, and HSMs (including SoftHSM2) do not support concurrent logins from different threads.

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 and both engine and provider OpenSSL APIs.

---
  Makefile                        |   2 +
  tools/binman/binman.rst         |  18 +++++
  tools/binman/btool/openssl.py   | 117 +++++++++++++++++++++++++++-----
  tools/binman/etype/x509_cert.py |  47 +++++++++++--
  tools/binman/ftest.py           | 110 ++++++++++++++++++++++++++++++
  5 files changed, 274 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 +8 -0
index 366491089ad9..e60eb7f572eb 100644
@@ -2161,6 +2161,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"
+

tools/binman/binman.rst BINMAN_INDIRS · line 2181

Quoted 10 lines
tools/binman/binman.rst +10 -0
+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"
+

OK, but why do we want to have this variable for storing the path to the module lib instead of using an openssl.cnf?

Also, this is stating it's for signing boot artifacts with an HSM, but that isn't true. It won't work with FIT images, which use DT properties instead (see fit,engine, fit,engine-keydir/key-name-hint.).

I'm assuming it's possible we want different keys for different boot artifacts, so this is also a bit too generic of a name?

Quoted 12 lines
tools/binman/binman.rst +0 -0
  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 +1 -0
index b26f087c4470..ec477a46a3d7 100644
@@ -11,10 +11,16 @@ Source code is at https://www.openssl.org/
  """
 
  import hashlib
+import os

tools/binman/btool/openssl.py Source code is at https://www.openssl.org/ · line 24

Quoted 10 lines
tools/binman/btool/openssl.py +5 -0
+import threading
 
  from binman import bintool
  from u_boot_pylib import tools
 
+# Serializes concurrent PKCS#11 signing operations. SoftHSM2 and many real
+# HSMs do not support simultaneous logins from multiple threads, so binman's
+# ThreadPoolExecutor would otherwise cause intermittent login failures.
+_pkcs11_lock = threading.Lock()
 

Is there really no external mechanism to make sure this cannot happen? or maybe some sort of session concept?

binman tests will run on multiple processes (see ConcurrentTestSuite) when not instructed to run on one thread (via -T 0, used for test coverage). My worry is whether this is multiprocess safe (hunch is no). Look at what we did for the FIT signing tests, we use different softhsm and openssl config files per file and I hope this is enough for openssl and softhsm to not get confused. Considering there's a multiprocessing.Lock(), there must be a reason for it no?

Quoted 13 lines
tools/binman/btool/openssl.py +7 -0
  VALID_SHAS = [256, 384, 512, 224]
  SHA_OIDS = {256:'2.16.840.1.101.3.4.2.1',
@@ -35,18 +41,89 @@ class Bintoolopenssl(bintool.Bintool):
          super().__init__(
              name, 'openssl cryptography toolkit',
              version_regex=r'OpenSSL (.*) \(', version_args='version')
+        self._use_provider = None
+
+    def _pkcs11_use_provider(self):
+        """Return True if the provider API should be used for PKCS#11 signing.
+
+        Checks whether the pkcs11 provider is available by running
+        'openssl list -providers'. The result is cached after the first call

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 60

Quoted 10 lines
tools/binman/btool/openssl.py +10 -0
+        to avoid spawning a subprocess on every signing operation.
+
+        Returns:
+            bool: True if provider should be used, False if engine should be used
+        """
+        if self._use_provider is None:
+            out = self.run_cmd('list', '-providers') or ''
+            self._use_provider = 'pkcs11' in out
+        return self._use_provider
+

Why force the user to use providers if one is available? Can't they use an engine even if a pkcs11 provider is available (e.g. you have both pkcs11 provider support via softhsm2, but only engine support for your HSM). Isn't this something the user can specify via openssl.cnf?

Quoted 310 lines
tools/binman/btool/openssl.py +78 -16
+    def _build_key_args(self, key_fname):
+        """Build openssl CLI arguments for the signing key.
+
+        Always add '-key key_fname', and for a PKCS#11 URI (pkcs11:...),
+        prepends either '-provider default -provider pkcs11' (if provider API
+        is available) or '-engine pkcs11 -keyform engine' (legacy fallback).
+        If the PKCS11_PIN environment variable is set, appends pin-value=<pin>
+        to the URI.
+
+        Args:
+            key_fname (str): Filename of .pem file or PKCS#11 URI
+
+        Returns:
+            list: openssl arguments for the key selection
+        """
+        if key_fname.startswith('pkcs11:'):
+            pin = os.environ.get('PKCS11_PIN')
+            if pin:
+                sep = '&' if '?' in key_fname else '?'
+                key_fname = f'{key_fname}{sep}pin-value={pin}'
+            if self._pkcs11_use_provider():
+                args = ['-provider', 'default', '-provider', 'pkcs11', '-key', key_fname]
+            else:
+                args = ['-engine', 'pkcs11', '-keyform', 'engine', '-key', key_fname]
+        else:
+            args = ['-key', key_fname]
+        return args
+
+    def _run_cmd_pkcs11(self, pkcs11_module, *args):
+        """Run an openssl command, optionally passing PKCS#11 module env vars.
+
+        When pkcs11_module is set, PKCS11_MODULE_PATH (engine) and
+        PKCS11_PROVIDER_MODULE (provider) are passed as extra environment
+        variables.
+        If already configured via openssl.cnf or the calling environment,
+        pkcs11_module can be None.
+
+        Args:
+            pkcs11_module (str or None): Path to the PKCS#11 shared library
+            *args: Arguments forwarded to run_cmd
+
+        Returns:
+            str: openssl output
+        """
+        if pkcs11_module:
+            extra_env = {
+                'PKCS11_MODULE_PATH': pkcs11_module,
+                'PKCS11_PROVIDER_MODULE': pkcs11_module,
+            }
+            with _pkcs11_lock:
+                return self.run_cmd(*args, extra_env=extra_env)
+        return self.run_cmd(*args)
 
      def x509_cert(self, cert_fname, input_fname, key_fname, cn, revision,
-                  config_fname):
+                  config_fname, pkcs11_module=None):
          """Create a certificate
 
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              cn (str): Common name
              revision (int): Revision number
              config_fname (str): Filename to write fconfig into
+            pkcs11_module (str or None): Path to PKCS#11 shared library, or
+                None if already configured via openssl.cnf or the environment
 
          Returns:
              str: Tool output
@@ -76,19 +153,20 @@ shaType                = OID:2.16.840.1.101.3.4.2.3
  shaValue               = FORMAT:HEX,OCT:{hashval}
  imageSize              = INTEGER:{len(indata)}
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509', *self._build_key_args(key_fname), '-nodes',
                  '-outform', 'DER', '-out', cert_fname, '-config', config_fname,
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_sysfw(self, cert_fname, input_fname, key_fname, sw_rev,
-                  config_fname, req_dist_name_dict, firewall_cert_data):
+                  config_fname, req_dist_name_dict, firewall_cert_data,
+                  pkcs11_module=None):
          """Create a certificate to be booted by system firmware
 
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing key-value pairs of
@@ -101,6 +179,8 @@ imageSize              = INTEGER:{len(indata)}
                  extended certificate
                - certificate (str): Extended firewall certificate with
                  the information for the firewall configurations.
+            pkcs11_module (str or None): Path to PKCS#11 shared library, or
+                None if already configured via openssl.cnf or the environment
 
          Returns:
              str: Tool output
@@ -146,20 +226,20 @@ authInPlace = INTEGER:{hex(firewall_cert_data['auth_in_place'])}
  numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']}
  {firewall_cert_data['certificate']}
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509', *self._build_key_args(key_fname), '-nodes',
                  '-outform', 'DER', '-out', cert_fname, '-config', config_fname,
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_rom(self, cert_fname, input_fname, key_fname, sw_rev,
                    config_fname, req_dist_name_dict, cert_type, bootcore,
-                  bootcore_opts, load_addr, sha, debug):
+                  bootcore_opts, load_addr, sha, debug, pkcs11_module=None):
          """Create a certificate
 
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing key-value pairs of
@@ -170,6 +250,8 @@ numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']}
              bootcore_opts(int): Booting core option, lockstep (0) or split (2) mode
              load_addr (int): Load address of image
              sha (int): Hash function
+            pkcs11_module (str or None): Path to PKCS#11 shared library, or
+                None if already configured via openssl.cnf or the environment
 
          Returns:
              str: Tool output
@@ -231,10 +313,10 @@ emailAddress           = {req_dist_name_dict['emailAddress']}
   coreDbgEn = INTEGER:0
   coreDbgSecEn = INTEGER:0
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509', *self._build_key_args(key_fname), '-nodes',
                  '-outform', 'DER', '-out', cert_fname, '-config', config_fname,
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_rom_combined(self, cert_fname, input_fname, key_fname, sw_rev,
                    config_fname, req_dist_name_dict, load_addr, sha, total_size, num_comps,
@@ -242,13 +324,14 @@ emailAddress           = {req_dist_name_dict['emailAddress']}
                    imagesize_sbl, hashval_sbl, load_addr_sysfw, imagesize_sysfw,
                    hashval_sysfw, load_addr_sysfw_data, imagesize_sysfw_data,
                    hashval_sysfw_data, sysfw_inner_cert_ext_boot_block,
-                  dm_data_ext_boot_block, bootcore_opts, debug):
+                  dm_data_ext_boot_block, bootcore_opts, debug,
+                  pkcs11_module=None):
          """Create a certificate
 
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing key-value pairs of
@@ -259,6 +342,8 @@ emailAddress           = {req_dist_name_dict['emailAddress']}
              load_addr (int): Load address of image
              sha (int): Hash function
              bootcore_opts (int): Booting core option, lockstep (0) or split (2) mode
+            pkcs11_module (str or None): Path to PKCS#11 shared library, or
+                None if already configured via openssl.cnf or the environment
 
          Returns:
              str: Tool output
@@ -342,10 +427,10 @@ coreDbgSecEn = INTEGER:0
 
  {dm_data_ext_boot_block}
          ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509', *self._build_key_args(key_fname), '-nodes',
                  '-outform', 'DER', '-out', cert_fname, '-config', config_fname,
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def fetch(self, method):
          """Fetch handler for openssl
tools/binman/etype/x509_cert.py +43 -4
index b6e8b0b4fb09..cdeff1a227a1 100644
@@ -19,6 +19,18 @@ class Entry_x509_cert(Entry_collection):
 
      Properties / Entry arguments:
          - content: List of phandles to entries to sign
+        - keyfile: Filename of the PEM key file used to sign the binary
+        - pkcs11-uri: PKCS#11 URI for signing via an HSM, e.g.
+            ``pkcs11:token=mytoken;object=mykey;type=private``. When provided
+            via ``-a pkcs11-uri=...`` on the binman command line (or via the
+            ``BINMAN_PKCS11_URI`` make variable), it overrides ``keyfile`` for
+            the signing operation.
+        - pkcs11-module: Path to the PKCS#11 shared library (.so), e.g.
+            ``/usr/lib/pkcs11/libsofthsm2.so``. Only needed when signing via
+            HSM and the module is not already configured via ``openssl.cnf`` or
+            the ``PKCS11_MODULE_PATH`` environment variable. Provided via
+            ``-a pkcs11-module=...`` or the ``BINMAN_PKCS11_MODULE`` make
+            variable.
 
      Output files:
          - input.<unique_name> - input file passed to openssl
@@ -27,6 +39,16 @@ class Entry_x509_cert(Entry_collection):
 
      openssl signs the provided data, writing the signature in this entry. This
      allows verification that the data is genuine
+
+    To sign with an HSM, pass the PKCS#11 URI and optionally the module path
+    at build time::
+
+        make BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private" \\
+             BINMAN_PKCS11_MODULE="/usr/lib/pkcs11/libsofthsm2.so" \\
+             PKCS11_PIN="1234"
+
+    The ``PKCS11_PIN`` environment variable is used by the openssl bintool to
+    append ``?pin-value=<pin>`` to the URI when required.
      """
      def __init__(self, section, etype, node):
          super().__init__(section, etype, node)
@@ -53,6 +75,8 @@ class Entry_x509_cert(Entry_collection):
          self.dm_data_ext_boot_block = None
          self.firewall_cert_data = None
          self.debug = False
+        self.pkcs11_uri = None
+        self.pkcs11_module = None
 
      def ReadNode(self):
          super().ReadNode()
@@ -61,6 +85,10 @@ class Entry_x509_cert(Entry_collection):
          self.key_fname = self.GetEntryArgsOrProps([
              EntryArg('keyfile', str)], required=True)[0]
          self.sw_rev = fdt_util.GetInt(self._node, 'sw-rev', 1)
+        self.pkcs11_uri = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-uri', str)], required=False)[0]
+        self.pkcs11_module = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-module', str)], required=False)[0]
 
      def GetCertificate(self, required, type='generic'):
          """Get the contents of this entry
@@ -80,6 +108,13 @@ class Entry_x509_cert(Entry_collection):
          if input_data is None:
              return None
 
+        # Override keyfile with the PKCS#11 URI if provided. This must be
+        # done here rather than in ReadNode(), because subclasses (e.g.
+        # ti_secure_rom, ti_secure) call super().ReadNode() and then
+        # overwrite self.key_fname with the DTS 'keyfile' property.
+        if self.pkcs11_uri:
+            self.key_fname = self.pkcs11_uri
+
          uniq = self.GetUniqueName()
          output_fname = tools.get_output_filename('cert.%s' % uniq)
          input_fname = tools.get_output_filename('input.%s' % uniq)
@@ -93,7 +128,8 @@ class Entry_x509_cert(Entry_collection):
                  key_fname=self.key_fname,
                  cn=self._cert_ca,
                  revision=self._cert_rev,
-                config_fname=config_fname)
+                config_fname=config_fname,
+                pkcs11_module=self.pkcs11_module)
          elif type == 'sysfw':
              stdout = self.openssl.x509_cert_sysfw(
                  cert_fname=output_fname,
@@ -102,7 +138,8 @@ class Entry_x509_cert(Entry_collection):
                  config_fname=config_fname,
                  sw_rev=self.sw_rev,
                  req_dist_name_dict=self.req_dist_name,
-                firewall_cert_data=self.firewall_cert_data)
+                firewall_cert_data=self.firewall_cert_data,
+                pkcs11_module=self.pkcs11_module)
          elif type == 'rom':
              stdout = self.openssl.x509_cert_rom(
                  cert_fname=output_fname,
@@ -116,7 +153,8 @@ class Entry_x509_cert(Entry_collection):
                  bootcore_opts=self.bootcore_opts,
                  load_addr=self.load_addr,
                  sha=self.sha,
-                debug=self.debug
+                debug=self.debug,
+                pkcs11_module=self.pkcs11_module
              )
          elif type == 'rom-combined':
              stdout = self.openssl.x509_cert_rom_combined(
@@ -143,7 +181,8 @@ class Entry_x509_cert(Entry_collection):
                  sysfw_inner_cert_ext_boot_block=self.sysfw_inner_cert_ext_boot_block,
                  dm_data_ext_boot_block=self.dm_data_ext_boot_block,
                  bootcore_opts=self.bootcore_opts,
-                debug=self.debug
+                debug=self.debug,
+                pkcs11_module=self.pkcs11_module
              )
          if stdout is not None:
              data = tools.read_file(output_fname)
tools/binman/ftest.py +0 -0
index ca5149ee654a..a23719c767c8 100644

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6889

Quoted 6 lines
tools/binman/ftest.py +3 -0
@@ -6884,6 +6884,116 @@ fdt         fdtmap                Extract the devicetree blob from the fdtmap
          err = stderr.getvalue()
          self.assertRegex(err, "Image 'image'.*missing bintools.*: openssl")
 
+    def testOpenSslBuildKeyArgsPem(self):
+        """Test _build_key_args with a regular PEM key file"""
+        openssl = bintool.Bintool.create('openssl')

Please always check the bintool is present with

self._CheckBintool(bintool)

such that we can skip tests if it isn't present instead of failing hard later.

Quoted 68 lines
tools/binman/ftest.py +68 -0
+        args = openssl._build_key_args('/path/to/key.pem')
+        self.assertEqual(['-key', '/path/to/key.pem'], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Provider(self):
+        """Test _build_key_args with a PKCS#11 URI when provider API is available"""
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='pkcs11 provider'):
+            args = openssl._build_key_args(uri)
+        self.assertEqual(['-provider', 'default', '-provider', 'pkcs11',
+                          '-key', uri], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Engine(self):
+        """Test _build_key_args with a PKCS#11 URI when only engine API is available"""
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd', return_value=''):
+            args = openssl._build_key_args(uri)
+        self.assertEqual(['-engine', 'pkcs11', '-keyform', 'engine',
+                          '-key', uri], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Pin(self):
+        """Test _build_key_args appends pin-value to URI when PKCS11_PIN is set"""
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.dict('os.environ', {'PKCS11_PIN': '1234'}):
+            with unittest.mock.patch.object(openssl, 'run_cmd',
+                                            return_value='pkcs11'):
+                args = openssl._build_key_args(uri)
+        self.assertIn(f'{uri}?pin-value=1234', args)
+
+    def testOpenSslBuildKeyArgsPkcs11PinExistingQuery(self):
+        """Test _build_key_args uses '&' separator when URI already has query params"""
+        uri = 'pkcs11:token=mytoken;object=mykey?module-path=/path/to/lib'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.dict('os.environ', {'PKCS11_PIN': '1234'}):
+            with unittest.mock.patch.object(openssl, 'run_cmd',
+                                            return_value='pkcs11'):
+                args = openssl._build_key_args(uri)
+        self.assertIn(f'{uri}&pin-value=1234', args)
+
+    def testOpenSslPkcs11UseProviderCached(self):
+        """Test that _pkcs11_use_provider caches its result after the first call"""
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='pkcs11') as mock_cmd:
+            result1 = openssl._pkcs11_use_provider()
+            result2 = openssl._pkcs11_use_provider()
+        self.assertTrue(result1)
+        self.assertTrue(result2)
+        mock_cmd.assert_called_once_with('list', '-providers')
+
+    def testOpenSslRunCmdPkcs11NoModule(self):
+        """Test _run_cmd_pkcs11 without a module just forwards to run_cmd"""
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='output') as mock_cmd:
+            result = openssl._run_cmd_pkcs11(None, 'version')
+        mock_cmd.assert_called_once_with('version')
+        self.assertEqual('output', result)
+
+    def testOpenSslRunCmdPkcs11WithModule(self):
+        """Test _run_cmd_pkcs11 passes module paths to run_cmd via extra_env"""
+        module = '/usr/lib/pkcs11/libsofthsm2.so'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='output') as mock_cmd:

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6967

Quoted 10 lines
tools/binman/ftest.py +10 -0
+            openssl._run_cmd_pkcs11(module, 'version')
+        mock_cmd.assert_called_once_with('version', extra_env={
+            'PKCS11_MODULE_PATH': module,
+            'PKCS11_PROVIDER_MODULE': module,
+        })
+
+    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'

FYI, the path isn't stable across all distros. Hence why we went for checking the path with p11-kit print-config to identify where it's located.

Quoted 5 lines
tools/binman/ftest.py +5 -0
+        original = bintool.Bintool.run_cmd
+        signing_args = []
+
+        def fake_openssl(self_tool, *args, binary=False, extra_env=None):
+            if self_tool.name != 'openssl':

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6982

Quoted 10 lines
tools/binman/ftest.py +10 -0
+                return original(self_tool, *args, binary=binary)
+            arg_list = list(args)
+            if arg_list == ['list', '-providers']:
+                return 'pkcs11 provider'
+            if '-out' in arg_list:
+                signing_args.extend(arg_list)
+                tools.write_file(arg_list[arg_list.index('-out') + 1],
+                                 b'\x00' * 32)
+            return ''
+

We need to check with a real openssl too, otherwise we just check the interface with openssl and not that it is actually doing what's expected (and may change, e.g. with a newer version of openssl).

Quoted 4 lines
tools/binman/ftest.py +4 -0
+        entry_args = {
+            'keyfile': self.TestFile('security/key.key'),
+            'pkcs11-uri': PKCS11_URI,
+            'pkcs11-module': PKCS11_MODULE,

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6996

Quoted 10 lines
tools/binman/ftest.py +10 -0
+        }
+        with unittest.mock.patch.object(bintool.Bintool, 'run_cmd',
+                                        new=fake_openssl):
+            data = self._DoReadFileDtb('security/x509_cert.dts',
+                                       entry_args=entry_args)[0]
+        self.assertGreater(len(data), len(U_BOOT_DATA))
+        self.assertEqual(U_BOOT_DATA, data[-4:])
+        self.assertIn('-provider pkcs11', ' '.join(signing_args))
+        self.assertIn(PKCS11_URI, signing_args)
+

Why going to such length to avoid actually using openssl? Generate/import a certificate in softhsm2 and check that the bintool actually returns what's expected? We do this for signing FIT images so I'm assuming this is something you could do here as well?

Cheers,
Quentin

#12 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

Hi Quentin,

Review

Quoted 2 lines · Quentin Schulz
(quoted diff) +2 -0
+BINMAN_PKCS11_MODULE
+    Path to the PKCS#11 shared library (.so) for HSM signing. When set,

it is

tools/binman/binman.rst BINMAN_INDIRS

Quoted 3 lines
tools/binman/binman.rst +3 -0
+    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

Quoted 4 lines

+ ``BINMAN_PKCS11_URI``::

OK, but why do we want to have this variable for storing the path to the module lib instead of using an openssl.cnf?

Agreed. I’ll drop BINMAN_PKCS11_MODULE and rely on external OpenSSL configuration (openssl.cnf) instead.

Quoted 6 lines

Also, this is stating it's for signing boot artifacts with an HSM, but that isn't true. It won't work with FIT images, which use DT properties instead (see fit,engine, fit,engine-keydir/key-name-hint.).

I'm assuming it's possible we want different keys for different boot artifacts, so this is also a bit too generic of a name?

Good point. I’ll scope this more precisely to X.509 usage. Would BINMAN_X509_PKCS11_URI be appropriate, or do you have a preferred naming convention here?

Quoted 1 line

+# Serializes concurrent PKCS#11 signing operations. SoftHSM2 and many

real

Quoted 1 line

+# HSMs do not support simultaneous logins from multiple threads, so

binman's

Quoted 9 lines
tools/binman/btool/openssl.py +2 -0
+# ThreadPoolExecutor would otherwise cause intermittent login failures.
+_pkcs11_lock = threading.Lock()

Is there really no external mechanism to make sure this cannot happen? or maybe some sort of session concept?

binman tests will run on multiple processes (see ConcurrentTestSuite) when not instructed to run on one thread (via -T 0, used for test coverage). My worry is whether this is multiprocess safe (hunch is no).

OK. I’ll investigate whether this can be handled externally (e.g. via token/session configuration) or if a more robust approach is needed.

Review

Quoted 2 lines
(quoted diff) +2 -0
+    def _pkcs11_use_provider(self):
+        """Return True if the provider API should be used for PKCS#11

signing.

Quoted 11 lines
tools/binman/btool/openssl.py +6 -0
+        ...
+        """
+        if self._use_provider is None:
+            out = self.run_cmd('list', '-providers') or ''
+            self._use_provider = 'pkcs11' in out
+        return self._use_provider

Why force the user to use providers if one is available? Can't they use an engine even if a pkcs11 provider is available (e.g. you have both pkcs11 provider support via softhsm2, but only engine support for your HSM). Isn't this something the user can specify via openssl.cnf?

From my testing with SoftHSM2:

- Provider-based flow: configuring openssl.cnf is sufficient. OpenSSL dispatches "pkcs11:" URIs via the STORE API without additional CLI arguments.
- Engine-based flow: configuring the engine in openssl.cnf alone is not sufficient; "-engine pkcs11 -keyform engine" must still be passed explicitly.

I would be fine with supporting provider-based flows only, as it simplifies the implementation and covers my use case (OpenEmbedded integration). However, I’m concerned about compatibility with older distributions where PKCS#11 provider support may not be available by default. What would you recommend in this case?

Quoted 5 lines
tools/binman/ftest.py +3 -0
+    def testOpenSslBuildKeyArgsPem(self):
+        """Test _build_key_args with a regular PEM key file"""
+        openssl = bintool.Bintool.create('openssl')

Please always check the bintool is present with

self._CheckBintool(bintool)

Quoted 1 line

such that we can skip tests if it isn't present instead of failing hard

later.

Will do.

Quoted 4 lines

+ PKCS11_MODULE = '/usr/lib/pkcs11/libsofthsm2.so'

FYI, the path isn't stable across all distros. Hence why we went for checking the path with p11-kit print-config to identify where it's

located.

Understood. I’ll switch to using p11-kit for discovery.

Quoted 11 lines
tools/binman/ftest.py +4 -0
+        def fake_openssl(self_tool, *args, binary=False, extra_env=None):
+            if self_tool.name != 'openssl':
+                return original(self_tool, *args, binary=binary)
+            ...

We need to check with a real openssl too, otherwise we just check the interface with openssl and not that it is actually doing what's expected.

Why going to such length to avoid actually using openssl? Generate/import a certificate in softhsm2 and check that the bintool actually returns what's expected?

Agreed. I’ll replace the mocked tests with a real SoftHSM2-based integration test.

Thanks for the detailed feedback.

Cheers,

Sergio Prado

Em seg., 27 de abr. de 2026 às 07:20, Quentin Schulz < [email protected]> escreveu:

Quoted 56 lines

Hi Sergio,

Quoted 52 lines · Sergio Prado

Allow X509 certificates used for TI K3 secure boot to be signed via an HSM using the PKCS#11 standard, so that the private key never leaves the hardware token.

Two new make variables are introduced:

BINMAN_PKCS11_URI PKCS#11 URI identifying the signing key, e.g.
pkcs11:token=mytoken;object=mykey;type=private
BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so), e.g.
/usr/lib/softhsm/libsofthsm2.so

When BINMAN_PKCS11_URI is set, it is forwarded to binman as the pkcs11-uri entry argument, overriding the keyfile property at signing time. BINMAN_PKCS11_MODULE is optional and only needed when the PKCS#11 library is not already configured via openssl.cnf or the PKCS11_MODULE_PATH environment variable.

The openssl bintool gains three helper methods:

_pkcs11_use_provider() auto-detects whether the OpenSSL pkcs11
provider (OpenSSL >= 3.1, pkcs11-provider) or the legacy pkcs11 engine (libp11) is available, by inspecting 'openssl list -providers'.

_build_key_args() builds the -key/-provider/-engine arguments for the
openssl command line. When PKCS11_PIN is set in the environment, its value is appended as ?pin-value=<pin> to the URI so that non-interactive signing works with both the provider and engine paths.

_run_cmd_pkcs11() sets PKCS11_MODULE_PATH and PKCS11_PROVIDER_MODULE
before invoking openssl when a module path is given, and serialises concurrent signing calls with a module-level lock. The lock is required because binman's ThreadPoolExecutor may invoke multiple signing operations simultaneously, and HSMs (including SoftHSM2) do not support concurrent logins from different threads.

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 and both engine and provider OpenSSL APIs.

---
  Makefile                        |   2 +
  tools/binman/binman.rst         |  18 +++++
  tools/binman/btool/openssl.py   | 117 +++++++++++++++++++++++++++-----
  tools/binman/etype/x509_cert.py |  47 +++++++++++--
  tools/binman/ftest.py           | 110 ++++++++++++++++++++++++++++++
  5 files changed, 274 insertions(+), 20 deletions(-)
Quoted 5 lines

Makefile cmd_binman = $(srctree)/tools/binman/binman $(if

Quoted 5 lines
Makefile +0 -0
index dfc95d314ddd..8d6c584b2731 100644
@@ -1701,6 +1701,8 @@ cmd_binman = $(srctree)/tools/binman/binman $(if

$(BINMAN_DEBUG),-D) \

Quoted 4 lines

Makefile cmd_binman = $(srctree)/tools/binman/binman $(if $(BINMAN_DEBUG),-D) \

Quoted 4 lines
Makefile +1 -0
              -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)") \

Quoted 1 line

Makefile cmd_binman = $(srctree)/tools/binman/binman $(if · line 1705

Quoted 1 line
Makefile +1 -0
+             $(if $(BINMAN_PKCS11_MODULE),-a

pkcs11-module="$(BINMAN_PKCS11_MODULE)") \

Quoted 9 lines

tools/binman/binman.rst BINMAN_INDIRS · line 2161

Quoted 9 lines
Makefile +0 -0
              $(BINMAN_$(@F))
 
  OBJCOPYFLAGS_u-boot.ldr.hex := -I binary -O ihex
tools/binman/binman.rst +0 -0
index 366491089ad9..e60eb7f572eb 100644
@@ -2161,6 +2161,24 @@ BINMAN_INDIRS
      Sets the search path for input files used by binman by adding one

or more

Quoted 4 lines

tools/binman/binman.rst BINMAN_INDIRS

Quoted 4 lines
tools/binman/binman.rst +2 -0
      `-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

Quoted 1 line

tools/binman/binman.rst BINMAN_INDIRS · line 2166

Quoted 1 line
tools/binman/binman.rst +1 -0
+    file on disk. When set, it is passed as ``-a pkcs11-uri=<uri>`` to

binman,

Quoted 1 line

tools/binman/binman.rst BINMAN_INDIRS · line 2167

Quoted 1 line
tools/binman/binman.rst +1 -0
+    which overrides the ``keyfile`` entry argument for all signing

operations.

Quoted 3 lines

tools/binman/binman.rst BINMAN_INDIRS

Quoted 3 lines
tools/binman/binman.rst +3 -0
+    Example::
+
+        make

BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private"

Quoted 3 lines

tools/binman/binman.rst BINMAN_INDIRS

Quoted 3 lines
tools/binman/binman.rst +3 -0
+
+BINMAN_PKCS11_MODULE
+    Path to the PKCS#11 shared library (.so) for HSM signing. When

set, it is

Quoted 1 line

tools/binman/binman.rst BINMAN_INDIRS · line 2174

Quoted 1 line
tools/binman/binman.rst +1 -0
+    passed as ``-a pkcs11-module=<path>`` to binman. Only needed when

the

Quoted 2 lines

tools/binman/binman.rst BINMAN_INDIRS · line 2176

Quoted 2 lines
tools/binman/binman.rst +2 -0
+    module is not already configured via ``openssl.cnf`` or the
+    ``PKCS11_MODULE_PATH`` environment variable. Typically used

together with

Quoted 3 lines

tools/binman/binman.rst BINMAN_INDIRS

Quoted 3 lines
tools/binman/binman.rst +3 -0
+    ``BINMAN_PKCS11_URI``::
+
+        make

BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private" \

Quoted 6 lines

tools/binman/binman.rst BINMAN_INDIRS · line 2181

Quoted 2 lines
tools/binman/binman.rst +2 -0
+             BINMAN_PKCS11_MODULE="/usr/lib/pkcs11/libsofthsm2.so"
+

OK, but why do we want to have this variable for storing the path to the module lib instead of using an openssl.cnf?

Quoted 9 lines

Also, this is stating it's for signing boot artifacts with an HSM, but that isn't true. It won't work with FIT images, which use DT properties instead (see fit,engine, fit,engine-keydir/key-name-hint.).

I'm assuming it's possible we want different keys for different boot artifacts, so this is also a bit too generic of a name?

Quoted 2 lines
tools/binman/binman.rst +0 -0
  BINMAN_TOOLPATHS
      Sets the search path for external tool used by binman by adding

one or more

Quoted 2 lines

Review

Quoted 2 lines
tools/binman/binman.rst +0 -0
      `--toolpath` arguments. See :ref:`External tools`.
(quoted diff) +0 -0

b/tools/binman/btool/openssl.py

Quoted 6 lines
Quoted 6 lines

index b26f087c4470..ec477a46a3d7 100644

tools/binman/btool/openssl.py +0 -0
@@ -11,10 +11,16 @@ Source code is at https://www.openssl.org/
  """
 
Quoted 8 lines

tools/binman/btool/openssl.py Source code is at https://www.openssl.org/

Quoted 8 lines
tools/binman/btool/openssl.py +3 -0
  import hashlib
+import os
+import threading
 
  from binman import bintool
  from u_boot_pylib import tools
 
+# Serializes concurrent PKCS#11 signing operations. SoftHSM2 and many

real

Quoted 1 line

tools/binman/btool/openssl.py Source code is at https://www.openssl.org/ · line 21

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+# HSMs do not support simultaneous logins from multiple threads, so

binman's

Quoted 15 lines

tools/binman/btool/openssl.py Source code is at https://www.openssl.org/ · line 24

Quoted 3 lines
tools/binman/btool/openssl.py +2 -0
+# ThreadPoolExecutor would otherwise cause intermittent login failures.
+_pkcs11_lock = threading.Lock()
 

Is there really no external mechanism to make sure this cannot happen? or maybe some sort of session concept?

binman tests will run on multiple processes (see ConcurrentTestSuite) when not instructed to run on one thread (via -T 0, used for test coverage). My worry is whether this is multiprocess safe (hunch is no). Look at what we did for the FIT signing tests, we use different softhsm and openssl config files per file and I hope this is enough for openssl and softhsm to not get confused. Considering there's a multiprocessing.Lock(), there must be a reason for it no?

Quoted 10 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 47

Quoted 10 lines
tools/binman/btool/openssl.py +4 -0
  VALID_SHAS = [256, 384, 512, 224]
  SHA_OIDS = {256:'2.16.840.1.101.3.4.2.1',
@@ -35,18 +41,89 @@ class Bintoolopenssl(bintool.Bintool):
          super().__init__(
              name, 'openssl cryptography toolkit',
              version_regex=r'OpenSSL (.*) \(', version_args='version')
+        self._use_provider = None
+
+    def _pkcs11_use_provider(self):
+        """Return True if the provider API should be used for PKCS#11

signing.

Quoted 3 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 3 lines
tools/binman/btool/openssl.py +3 -0
+
+        Checks whether the pkcs11 provider is available by running
+        'openssl list -providers'. The result is cached after the

first call

Quoted 4 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 4 lines
tools/binman/btool/openssl.py +4 -0
+        to avoid spawning a subprocess on every signing operation.
+
+        Returns:
+            bool: True if provider should be used, False if engine

should be used

Quoted 7 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 60

Quoted 6 lines
tools/binman/btool/openssl.py +6 -0
+        """
+        if self._use_provider is None:
+            out = self.run_cmd('list', '-providers') or ''
+            self._use_provider = 'pkcs11' in out
+        return self._use_provider
+
Quoted 9 lines

Why force the user to use providers if one is available? Can't they use an engine even if a pkcs11 provider is available (e.g. you have both pkcs11 provider support via softhsm2, but only engine support for your HSM). Isn't this something the user can specify via openssl.cnf?

Quoted 4 lines
tools/binman/btool/openssl.py +4 -0
+    def _build_key_args(self, key_fname):
+        """Build openssl CLI arguments for the signing key.
+
+        Always add '-key key_fname', and for a PKCS#11 URI

(pkcs11:...),

Quoted 1 line

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 65

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+        prepends either '-provider default -provider pkcs11' (if

provider API

Quoted 1 line

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 66

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+        is available) or '-engine pkcs11 -keyform engine' (legacy

fallback).

Quoted 1 line

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 67

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+        If the PKCS11_PIN environment variable is set, appends

pin-value=<pin>

Quoted 7 lines
Quoted 7 lines
tools/binman/btool/openssl.py +7 -0
+        to the URI.
+
+        Args:
+            key_fname (str): Filename of .pem file or PKCS#11 URI
+
+        Returns:
+            list: openssl arguments for the key selection
Quoted 8 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 8 lines
tools/binman/btool/openssl.py +8 -0
+        """
+        if key_fname.startswith('pkcs11:'):
+            pin = os.environ.get('PKCS11_PIN')
+            if pin:
+                sep = '&' if '?' in key_fname else '?'
+                key_fname = f'{key_fname}{sep}pin-value={pin}'
+            if self._pkcs11_use_provider():
+                args = ['-provider', 'default', '-provider', 'pkcs11',

'-key', key_fname]

Quoted 2 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 84

Quoted 2 lines
tools/binman/btool/openssl.py +2 -0
+            else:
+                args = ['-engine', 'pkcs11', '-keyform', 'engine',

'-key', key_fname]

Quoted 6 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 6 lines
tools/binman/btool/openssl.py +6 -0
+        else:
+            args = ['-key', key_fname]
+        return args
+
+    def _run_cmd_pkcs11(self, pkcs11_module, *args):
+        """Run an openssl command, optionally passing PKCS#11 module

env vars.

Quoted 3 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 3 lines
tools/binman/btool/openssl.py +3 -0
+
+        When pkcs11_module is set, PKCS11_MODULE_PATH (engine) and
+        PKCS11_PROVIDER_MODULE (provider) are passed as extra

environment

Quoted 2 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 95

Quoted 2 lines
tools/binman/btool/openssl.py +2 -0
+        variables.
+        If already configured via openssl.cnf or the calling

environment,

Quoted 4 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 4 lines
tools/binman/btool/openssl.py +4 -0
+        pkcs11_module can be None.
+
+        Args:
+            pkcs11_module (str or None): Path to the PKCS#11 shared

library

Quoted 14 lines
Quoted 14 lines
tools/binman/btool/openssl.py +13 -0
+            *args: Arguments forwarded to run_cmd
+
+        Returns:
+            str: openssl output
+        """
+        if pkcs11_module:
+            extra_env = {
+                'PKCS11_MODULE_PATH': pkcs11_module,
+                'PKCS11_PROVIDER_MODULE': pkcs11_module,
+            }
+            with _pkcs11_lock:
+                return self.run_cmd(*args, extra_env=extra_env)
+        return self.run_cmd(*args)
 
Quoted 1 line

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 114

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
      def x509_cert(self, cert_fname, input_fname, key_fname, cn,

revision,

Quoted 4 lines
Quoted 4 lines
tools/binman/btool/openssl.py +1 -1
-                  config_fname):
+                  config_fname, pkcs11_module=None):
          """Create a certificate
 
Quoted 9 lines

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool):

Quoted 9 lines
tools/binman/btool/openssl.py +2 -1
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              cn (str): Common name
              revision (int): Revision number
              config_fname (str): Filename to write fconfig into
+            pkcs11_module (str or None): Path to PKCS#11 shared

library, or

Quoted 1 line

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 126

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+                None if already configured via openssl.cnf or the

environment

Quoted 9 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3 · line 156

Quoted 9 lines
tools/binman/btool/openssl.py +1 -1
          Returns:
              str: Tool output
@@ -76,19 +153,20 @@ shaType                = OID:2.16.840.1.101.3.4.2.3
  shaValue               = FORMAT:HEX,OCT:{hashval}
  imageSize              = INTEGER:{len(indata)}
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509',

*self._build_key_args(key_fname), '-nodes',

Quoted 1 line

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3 · line 157

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                  '-outform', 'DER', '-out', cert_fname, '-config',

config_fname,

Quoted 5 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3

Quoted 5 lines
tools/binman/btool/openssl.py +1 -1
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_sysfw(self, cert_fname, input_fname, key_fname,

sw_rev,

Quoted 1 line

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3 · line 85

Quoted 1 line
tools/binman/btool/openssl.py +0 -1
-                  config_fname, req_dist_name_dict,

firewall_cert_data):

Quoted 4 lines
Quoted 4 lines
tools/binman/btool/openssl.py +2 -0
+                  config_fname, req_dist_name_dict, firewall_cert_data,
+                  pkcs11_module=None):
          """Create a certificate to be booted by system firmware
 
Quoted 8 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3

Quoted 8 lines
tools/binman/btool/openssl.py +1 -1
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing

key-value pairs of

Quoted 5 lines

tools/binman/btool/openssl.py imageSize = INTEGER:{len(indata)} · line 182

Quoted 5 lines
tools/binman/btool/openssl.py +1 -0
@@ -101,6 +179,8 @@ imageSize              = INTEGER:{len(indata)}
                  extended certificate
                - certificate (str): Extended firewall certificate with
                  the information for the firewall configurations.
+            pkcs11_module (str or None): Path to PKCS#11 shared

library, or

Quoted 1 line

tools/binman/btool/openssl.py imageSize = INTEGER:{len(indata)} · line 183

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+                None if already configured via openssl.cnf or the

environment

Quoted 4 lines

tools/binman/btool/openssl.py authInPlace =

Quoted 4 lines
tools/binman/btool/openssl.py +0 -0
          Returns:
              str: Tool output
@@ -146,20 +226,20 @@ authInPlace =

INTEGER:{hex(firewall_cert_data['auth_in_place'])}

Quoted 5 lines

tools/binman/btool/openssl.py authInPlace = INTEGER:{hex(firewall_cert_data['auth_in_place'])}

Quoted 5 lines
tools/binman/btool/openssl.py +1 -1
  numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']}
  {firewall_cert_data['certificate']}
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509',

*self._build_key_args(key_fname), '-nodes',

Quoted 1 line

tools/binman/btool/openssl.py authInPlace = · line 230

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                  '-outform', 'DER', '-out', cert_fname, '-config',

config_fname,

Quoted 5 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3

Quoted 5 lines
tools/binman/btool/openssl.py +1 -1
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_rom(self, cert_fname, input_fname, key_fname,

sw_rev,

Quoted 1 line

tools/binman/btool/openssl.py authInPlace = · line 235

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                    config_fname, req_dist_name_dict, cert_type,

bootcore,

Quoted 2 lines

tools/binman/btool/openssl.py authInPlace = · line 236

Quoted 2 lines
tools/binman/btool/openssl.py +1 -1
-                  bootcore_opts, load_addr, sha, debug):
+                  bootcore_opts, load_addr, sha, debug,

pkcs11_module=None):

Quoted 10 lines

tools/binman/btool/openssl.py authInPlace = INTEGER:{hex(firewall_cert_data['auth_in_place'])}

Quoted 10 lines
tools/binman/btool/openssl.py +1 -1
          """Create a certificate
 
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing

key-value pairs of

Quoted 1 line

tools/binman/btool/openssl.py numFirewallRegions =

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
@@ -170,6 +250,8 @@ numFirewallRegions =

INTEGER:{firewall_cert_data['num_firewalls']}

Quoted 1 line

tools/binman/btool/openssl.py numFirewallRegions = · line 250

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
              bootcore_opts(int): Booting core option, lockstep (0) or

split (2) mode

Quoted 3 lines

tools/binman/btool/openssl.py numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']}

Quoted 3 lines
tools/binman/btool/openssl.py +1 -0
              load_addr (int): Load address of image
              sha (int): Hash function
+            pkcs11_module (str or None): Path to PKCS#11 shared

library, or

Quoted 1 line

tools/binman/btool/openssl.py numFirewallRegions = · line 254

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+                None if already configured via openssl.cnf or the

environment

Quoted 4 lines

tools/binman/btool/openssl.py emailAddress =

Quoted 4 lines
tools/binman/btool/openssl.py +0 -0
          Returns:
              str: Tool output
@@ -231,10 +313,10 @@ emailAddress           =

{req_dist_name_dict['emailAddress']}

Quoted 5 lines

tools/binman/btool/openssl.py emailAddress = {req_dist_name_dict['emailAddress']}

Quoted 5 lines
tools/binman/btool/openssl.py +1 -1
   coreDbgEn = INTEGER:0
   coreDbgSecEn = INTEGER:0
  ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509',

*self._build_key_args(key_fname), '-nodes',

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 317

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                  '-outform', 'DER', '-out', cert_fname, '-config',

config_fname,

Quoted 5 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3

Quoted 5 lines
tools/binman/btool/openssl.py +1 -1
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def x509_cert_rom_combined(self, cert_fname, input_fname,

key_fname, sw_rev,

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 322

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                    config_fname, req_dist_name_dict, load_addr, sha,

total_size, num_comps,

Quoted 1 line

tools/binman/btool/openssl.py emailAddress =

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
@@ -242,13 +324,14 @@ emailAddress           =

{req_dist_name_dict['emailAddress']}

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 324

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                    imagesize_sbl, hashval_sbl, load_addr_sysfw,

imagesize_sysfw,

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 325

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                    hashval_sysfw, load_addr_sysfw_data,

imagesize_sysfw_data,

Quoted 6 lines
Quoted 6 lines
tools/binman/btool/openssl.py +2 -1
                    hashval_sysfw_data, sysfw_inner_cert_ext_boot_block,
-                  dm_data_ext_boot_block, bootcore_opts, debug):
+                  dm_data_ext_boot_block, bootcore_opts, debug,
+                  pkcs11_module=None):
          """Create a certificate
 
Quoted 8 lines

tools/binman/btool/openssl.py shaType = OID:2.16.840.1.101.3.4.2.3

Quoted 8 lines
tools/binman/btool/openssl.py +1 -1
          Args:
              cert_fname (str): Filename of certificate to create
              input_fname (str): Filename containing data to sign
-            key_fname (str): Filename of .pem file
+            key_fname (str): Filename of .pem file or PKCS#11 URI
              sw_rev (int): Software revision
              config_fname (str): Filename to write fconfig into
              req_dist_name_dict (dict): Dictionary containing

key-value pairs of

Quoted 1 line

tools/binman/btool/openssl.py emailAddress =

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
@@ -259,6 +342,8 @@ emailAddress           =

{req_dist_name_dict['emailAddress']}

Quoted 3 lines

tools/binman/btool/openssl.py numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']}

Quoted 3 lines
tools/binman/btool/openssl.py +0 -0
              load_addr (int): Load address of image
              sha (int): Hash function
              bootcore_opts (int): Booting core option, lockstep (0) or

split (2) mode

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 345

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+            pkcs11_module (str or None): Path to PKCS#11 shared

library, or

Quoted 1 line

tools/binman/btool/openssl.py emailAddress = · line 346

Quoted 1 line
tools/binman/btool/openssl.py +1 -0
+                None if already configured via openssl.cnf or the

environment

Quoted 9 lines

tools/binman/btool/openssl.py coreDbgSecEn = INTEGER:0 · line 430

Quoted 9 lines
tools/binman/btool/openssl.py +1 -1
          Returns:
              str: Tool output
@@ -342,10 +427,10 @@ coreDbgSecEn = INTEGER:0
 
  {dm_data_ext_boot_block}
          ''', file=outf)
-        args = ['req', '-new', '-x509', '-key', key_fname, '-nodes',
+        args = ['req', '-new', '-x509',

*self._build_key_args(key_fname), '-nodes',

Quoted 1 line

tools/binman/btool/openssl.py coreDbgSecEn = INTEGER:0 · line 431

Quoted 1 line
tools/binman/btool/openssl.py +0 -0
                  '-outform', 'DER', '-out', cert_fname, '-config',

config_fname,

Quoted 7 lines

Review

Quoted 7 lines
tools/binman/btool/openssl.py +1 -1
                  '-sha512']
-        return self.run_cmd(*args)
+        return self._run_cmd_pkcs11(pkcs11_module, *args)
 
      def fetch(self, method):
          """Fetch handler for openssl
(quoted diff) +0 -0

b/tools/binman/etype/x509_cert.py

Quoted 10 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 24

Quoted 10 lines

index b6e8b0b4fb09..cdeff1a227a1 100644

tools/binman/etype/x509_cert.py +3 -0
@@ -19,6 +19,18 @@ class Entry_x509_cert(Entry_collection):
 
      Properties / Entry arguments:
          - content: List of phandles to entries to sign
+        - keyfile: Filename of the PEM key file used to sign the binary
+        - pkcs11-uri: PKCS#11 URI for signing via an HSM, e.g.
+            ``pkcs11:token=mytoken;object=mykey;type=private``. When

provided

Quoted 1 line

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 25

Quoted 1 line
tools/binman/etype/x509_cert.py +1 -0
+            via ``-a pkcs11-uri=...`` on the binman command line (or

via the

Quoted 1 line

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 26

Quoted 1 line
tools/binman/etype/x509_cert.py +1 -0
+            ``BINMAN_PKCS11_URI`` make variable), it overrides

``keyfile`` for

Quoted 3 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection):

Quoted 3 lines
tools/binman/etype/x509_cert.py +3 -0
+            the signing operation.
+        - pkcs11-module: Path to the PKCS#11 shared library (.so), e.g.
+            ``/usr/lib/pkcs11/libsofthsm2.so``. Only needed when

signing via

Quoted 1 line

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 30

Quoted 1 line
tools/binman/etype/x509_cert.py +1 -0
+            HSM and the module is not already configured via

``openssl.cnf`` or

Quoted 1 line

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 31

Quoted 1 line
tools/binman/etype/x509_cert.py +1 -0
+            the ``PKCS11_MODULE_PATH`` environment variable. Provided

via

Quoted 1 line

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 32

Quoted 1 line
tools/binman/etype/x509_cert.py +1 -0
+            ``-a pkcs11-module=...`` or the ``BINMAN_PKCS11_MODULE``

make

Quoted 7 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 40

Quoted 7 lines
tools/binman/etype/x509_cert.py +1 -0
+            variable.
 
      Output files:
          - input.<unique_name> - input file passed to openssl
@@ -27,6 +39,16 @@ class Entry_x509_cert(Entry_collection):
 
      openssl signs the provided data, writing the signature in this

entry. This

Quoted 3 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection):

Quoted 3 lines
tools/binman/etype/x509_cert.py +2 -0
      allows verification that the data is genuine
+
+    To sign with an HSM, pass the PKCS#11 URI and optionally the

module path

Quoted 3 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection):

Quoted 3 lines
tools/binman/etype/x509_cert.py +3 -0
+    at build time::
+
+        make

BINMAN_PKCS11_URI="pkcs11:token=mytoken;object=mykey;type=private" \\

Quoted 4 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection):

Quoted 4 lines
tools/binman/etype/x509_cert.py +4 -0
+             BINMAN_PKCS11_MODULE="/usr/lib/pkcs11/libsofthsm2.so" \\
+             PKCS11_PIN="1234"
+
+    The ``PKCS11_PIN`` environment variable is used by the openssl

bintool to

Quoted 22 lines
Quoted 22 lines
tools/binman/etype/x509_cert.py +7 -0
+    append ``?pin-value=<pin>`` to the URI when required.
      """
      def __init__(self, section, etype, node):
          super().__init__(section, etype, node)
@@ -53,6 +75,8 @@ class Entry_x509_cert(Entry_collection):
          self.dm_data_ext_boot_block = None
          self.firewall_cert_data = None
          self.debug = False
+        self.pkcs11_uri = None
+        self.pkcs11_module = None
 
      def ReadNode(self):
          super().ReadNode()
@@ -61,6 +85,10 @@ class Entry_x509_cert(Entry_collection):
          self.key_fname = self.GetEntryArgsOrProps([
              EntryArg('keyfile', str)], required=True)[0]
          self.sw_rev = fdt_util.GetInt(self._node, 'sw-rev', 1)
+        self.pkcs11_uri = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-uri', str)], required=False)[0]
+        self.pkcs11_module = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-module', str)], required=False)[0]
 
Quoted 7 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 111

Quoted 7 lines
tools/binman/etype/x509_cert.py +1 -0
      def GetCertificate(self, required, type='generic'):
          """Get the contents of this entry
@@ -80,6 +108,13 @@ class Entry_x509_cert(Entry_collection):
          if input_data is None:
              return None
 
+        # Override keyfile with the PKCS#11 URI if provided. This must

be

Quoted 33 lines
Quoted 33 lines
tools/binman/etype/x509_cert.py +10 -2
+        # done here rather than in ReadNode(), because subclasses (e.g.
+        # ti_secure_rom, ti_secure) call super().ReadNode() and then
+        # overwrite self.key_fname with the DTS 'keyfile' property.
+        if self.pkcs11_uri:
+            self.key_fname = self.pkcs11_uri
+
          uniq = self.GetUniqueName()
          output_fname = tools.get_output_filename('cert.%s' % uniq)
          input_fname = tools.get_output_filename('input.%s' % uniq)
@@ -93,7 +128,8 @@ class Entry_x509_cert(Entry_collection):
                  key_fname=self.key_fname,
                  cn=self._cert_ca,
                  revision=self._cert_rev,
-                config_fname=config_fname)
+                config_fname=config_fname,
+                pkcs11_module=self.pkcs11_module)
          elif type == 'sysfw':
              stdout = self.openssl.x509_cert_sysfw(
                  cert_fname=output_fname,
@@ -102,7 +138,8 @@ class Entry_x509_cert(Entry_collection):
                  config_fname=config_fname,
                  sw_rev=self.sw_rev,
                  req_dist_name_dict=self.req_dist_name,
-                firewall_cert_data=self.firewall_cert_data)
+                firewall_cert_data=self.firewall_cert_data,
+                pkcs11_module=self.pkcs11_module)
          elif type == 'rom':
              stdout = self.openssl.x509_cert_rom(
                  cert_fname=output_fname,
@@ -116,7 +153,8 @@ class Entry_x509_cert(Entry_collection):
                  bootcore_opts=self.bootcore_opts,
                  load_addr=self.load_addr,
                  sha=self.sha,
Quoted 8 lines

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 181

Quoted 8 lines
tools/binman/etype/x509_cert.py +2 -1
-                debug=self.debug
+                debug=self.debug,
+                pkcs11_module=self.pkcs11_module
              )
          elif type == 'rom-combined':
              stdout = self.openssl.x509_cert_rom_combined(
@@ -143,7 +181,8 @@ class Entry_x509_cert(Entry_collection):
 

sysfw_inner_cert_ext_boot_block=self.sysfw_inner_cert_ext_boot_block,

Quoted 5 lines
Quoted 5 lines
tools/binman/etype/x509_cert.py +2 -1
                  dm_data_ext_boot_block=self.dm_data_ext_boot_block,
                  bootcore_opts=self.bootcore_opts,
-                debug=self.debug
+                debug=self.debug,
+                pkcs11_module=self.pkcs11_module
Quoted 8 lines

tools/binman/ftest.py fdt fdtmap Extract the

Quoted 8 lines
tools/binman/etype/x509_cert.py +0 -0
              )
          if stdout is not None:
              data = tools.read_file(output_fname)
tools/binman/ftest.py +0 -0
index ca5149ee654a..a23719c767c8 100644
@@ -6884,6 +6884,116 @@ 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 +0 -0
          err = stderr.getvalue()
          self.assertRegex(err, "Image 'image'.*missing bintools.*:

openssl")

Quoted 5 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6889

Quoted 4 lines
tools/binman/ftest.py +3 -0
+    def testOpenSslBuildKeyArgsPem(self):
+        """Test _build_key_args with a regular PEM key file"""
+        openssl = bintool.Bintool.create('openssl')
Quoted 12 lines

Please always check the bintool is present with

self._CheckBintool(bintool)

such that we can skip tests if it isn't present instead of failing hard later.

Quoted 5 lines
tools/binman/ftest.py +5 -0
+        args = openssl._build_key_args('/path/to/key.pem')
+        self.assertEqual(['-key', '/path/to/key.pem'], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Provider(self):
+        """Test _build_key_args with a PKCS#11 URI when provider API

is available"""

Quoted 4 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 4 lines
tools/binman/ftest.py +4 -0
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='pkcs11

provider'):

Quoted 2 lines

tools/binman/ftest.py fdt fdtmap Extract the · line 6899

Quoted 2 lines
tools/binman/ftest.py +2 -0
+            args = openssl._build_key_args(uri)
+        self.assertEqual(['-provider', 'default', '-provider',

'pkcs11',

Quoted 4 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 4 lines
tools/binman/ftest.py +4 -0
+                          '-key', uri], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Engine(self):
+        """Test _build_key_args with a PKCS#11 URI when only engine

API is available"""

Quoted 3 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6897

Quoted 3 lines
tools/binman/ftest.py +3 -0
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',

return_value=''):

Quoted 6 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 6 lines
tools/binman/ftest.py +6 -0
+            args = openssl._build_key_args(uri)
+        self.assertEqual(['-engine', 'pkcs11', '-keyform', 'engine',
+                          '-key', uri], args)
+
+    def testOpenSslBuildKeyArgsPkcs11Pin(self):
+        """Test _build_key_args appends pin-value to URI when

PKCS11_PIN is set"""

Quoted 3 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 3 lines
tools/binman/ftest.py +3 -0
+        uri = 'pkcs11:token=mytoken;object=mykey'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.dict('os.environ', {'PKCS11_PIN':

'1234'}):

Quoted 7 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 7 lines
tools/binman/ftest.py +7 -0
+            with unittest.mock.patch.object(openssl, 'run_cmd',
+                                            return_value='pkcs11'):
+                args = openssl._build_key_args(uri)
+        self.assertIn(f'{uri}?pin-value=1234', args)
+
+    def testOpenSslBuildKeyArgsPkcs11PinExistingQuery(self):
+        """Test _build_key_args uses '&' separator when URI already

has query params"""

Quoted 1 line

tools/binman/ftest.py fdt fdtmap Extract the · line 6923

Quoted 1 line
tools/binman/ftest.py +1 -0
+        uri =

'pkcs11:token=mytoken;object=mykey?module-path=/path/to/lib'

Quoted 2 lines

tools/binman/ftest.py fdt fdtmap Extract the · line 6925

Quoted 2 lines
tools/binman/ftest.py +2 -0
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.dict('os.environ', {'PKCS11_PIN':

'1234'}):

Quoted 7 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 7 lines
tools/binman/ftest.py +7 -0
+            with unittest.mock.patch.object(openssl, 'run_cmd',
+                                            return_value='pkcs11'):
+                args = openssl._build_key_args(uri)
+        self.assertIn(f'{uri}&pin-value=1234', args)
+
+    def testOpenSslPkcs11UseProviderCached(self):
+        """Test that _pkcs11_use_provider caches its result after the

first call"""

Quoted 3 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 3 lines
tools/binman/ftest.py +3 -0
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='pkcs11') as

mock_cmd:

Quoted 8 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 8 lines
tools/binman/ftest.py +8 -0
+            result1 = openssl._pkcs11_use_provider()
+            result2 = openssl._pkcs11_use_provider()
+        self.assertTrue(result1)
+        self.assertTrue(result2)
+        mock_cmd.assert_called_once_with('list', '-providers')
+
+    def testOpenSslRunCmdPkcs11NoModule(self):
+        """Test _run_cmd_pkcs11 without a module just forwards to

run_cmd"""

Quoted 3 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 3 lines
tools/binman/ftest.py +3 -0
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='output') as

mock_cmd:

Quoted 6 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 6 lines
tools/binman/ftest.py +6 -0
+            result = openssl._run_cmd_pkcs11(None, 'version')
+        mock_cmd.assert_called_once_with('version')
+        self.assertEqual('output', result)
+
+    def testOpenSslRunCmdPkcs11WithModule(self):
+        """Test _run_cmd_pkcs11 passes module paths to run_cmd via

extra_env"""

Quoted 4 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 4 lines
tools/binman/ftest.py +4 -0
+        module = '/usr/lib/pkcs11/libsofthsm2.so'
+        openssl = bintool.Bintool.create('openssl')
+        with unittest.mock.patch.object(openssl, 'run_cmd',
+                                        return_value='output') as

mock_cmd:

Quoted 8 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 8 lines
tools/binman/ftest.py +8 -0
+            openssl._run_cmd_pkcs11(module, 'version')
+        mock_cmd.assert_called_once_with('version', extra_env={
+            'PKCS11_MODULE_PATH': module,
+            'PKCS11_PROVIDER_MODULE': module,
+        })
+
+    def testX509CertPkcs11(self):
+        """Test X509 certificate creation using a PKCS#11 URI instead

of a key file"""

Quoted 5 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6967

Quoted 2 lines
tools/binman/ftest.py +2 -0
+        PKCS11_URI = 'pkcs11:token=test;object=mykey;type=private'
+        PKCS11_MODULE = '/usr/lib/pkcs11/libsofthsm2.so'

FYI, the path isn't stable across all distros. Hence why we went for checking the path with p11-kit print-config to identify where it's

located.

Quoted 5 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap

Quoted 5 lines
tools/binman/ftest.py +4 -0
+        original = bintool.Bintool.run_cmd
+        signing_args = []
+
+        def fake_openssl(self_tool, *args, binary=False,

extra_env=None):

Quoted 38 lines

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6982

Quoted 11 lines
tools/binman/ftest.py +11 -0
+            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:
+                signing_args.extend(arg_list)
+                tools.write_file(arg_list[arg_list.index('-out') + 1],
+                                 b'\x00' * 32)
+            return ''
+

We need to check with a real openssl too, otherwise we just check the interface with openssl and not that it is actually doing what's expected (and may change, e.g. with a newer version of openssl).

Quoted 4 lines
tools/binman/ftest.py +4 -0
+        entry_args = {
+            'keyfile': self.TestFile('security/key.key'),
+            'pkcs11-uri': PKCS11_URI,
+            'pkcs11-module': PKCS11_MODULE,

tools/binman/ftest.py fdt fdtmap Extract the devicetree blob from the fdtmap · line 6996

Quoted 10 lines
tools/binman/ftest.py +10 -0
+        }
+        with unittest.mock.patch.object(bintool.Bintool, 'run_cmd',
+                                        new=fake_openssl):
+            data = self._DoReadFileDtb('security/x509_cert.dts',
+                                       entry_args=entry_args)[0]
+        self.assertGreater(len(data), len(U_BOOT_DATA))
+        self.assertEqual(U_BOOT_DATA, data[-4:])
+        self.assertIn('-provider pkcs11', ' '.join(signing_args))
+        self.assertIn(PKCS11_URI, signing_args)
+

Why going to such length to avoid actually using openssl? Generate/import a certificate in softhsm2 and check that the bintool actually returns what's expected? We do this for signing FIT images so I'm assuming this is something you could do here as well?

Cheers,
Quentin

#13 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

Hi Sergio,

Quoted 23 lines · Sergio Prado

Hi Quentin,

Review

Quoted 2 lines · Quentin Schulz
(quoted diff) +2 -0
+BINMAN_PKCS11_MODULE
+    Path to the PKCS#11 shared library (.so) for HSM signing. When set,

it is

tools/binman/binman.rst BINMAN_INDIRS

Quoted 3 lines
tools/binman/binman.rst +3 -0
+    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

Quoted 4 lines

+ ``BINMAN_PKCS11_URI``::

OK, but why do we want to have this variable for storing the path to the module lib instead of using an openssl.cnf?

Agreed. I’ll drop BINMAN_PKCS11_MODULE and rely on external OpenSSL configuration (openssl.cnf) instead.

Quoted 4 lines

Also, this is stating it's for signing boot artifacts with an HSM, but that isn't true. It won't work with FIT images, which use DT properties instead (see fit,engine, fit,engine-keydir/key-name-hint.).

Quoted 7 lines
Quoted 2 lines

I'm assuming it's possible we want different keys for different boot artifacts, so this is also a bit too generic of a name?

Good point. I’ll scope this more precisely to X.509 usage. Would BINMAN_X509_PKCS11_URI be appropriate, or do you have a preferred naming convention here?

Is this really PKCS11-specific? Is there no other way to get an x509 than by PKCS11 or plaintext file? Trying to think about potentially having other providers needing something similar and then setting BINMAN_X509_PKCS11_URI for that would be confusing.

Quoted 32 lines
Quoted 1 line

+# Serializes concurrent PKCS#11 signing operations. SoftHSM2 and many

real

Quoted 1 line

+# HSMs do not support simultaneous logins from multiple threads, so

binman's

Quoted 9 lines
tools/binman/btool/openssl.py +2 -0
+# ThreadPoolExecutor would otherwise cause intermittent login failures.
+_pkcs11_lock = threading.Lock()

Is there really no external mechanism to make sure this cannot happen? or maybe some sort of session concept?

binman tests will run on multiple processes (see ConcurrentTestSuite) when not instructed to run on one thread (via -T 0, used for test coverage). My worry is whether this is multiprocess safe (hunch is no).

OK. I’ll investigate whether this can be handled externally (e.g. via token/session configuration) or if a more robust approach is needed.

Review

Quoted 2 lines
(quoted diff) +2 -0
+    def _pkcs11_use_provider(self):
+        """Return True if the provider API should be used for PKCS#11

signing.

Quoted 11 lines
tools/binman/btool/openssl.py +6 -0
+        ...
+        """
+        if self._use_provider is None:
+            out = self.run_cmd('list', '-providers') or ''
+            self._use_provider = 'pkcs11' in out
+        return self._use_provider

Why force the user to use providers if one is available? Can't they use an engine even if a pkcs11 provider is available (e.g. you have both pkcs11 provider support via softhsm2, but only engine support for your HSM). Isn't this something the user can specify via openssl.cnf?

Quoted 9 lines

From my testing with SoftHSM2:

- Provider-based flow: configuring openssl.cnf is sufficient. OpenSSL dispatches "pkcs11:" URIs via the STORE API without additional CLI arguments.
- Engine-based flow: configuring the engine in openssl.cnf alone is not sufficient; "-engine pkcs11 -keyform engine" must still be passed explicitly.

Being curious now, I'm wondering if setting the -key to org.openssl.engine:pkcs11:<key> would be enough on OpenSSL 3.x? C.f. https://docs.openssl.org/3.0/man1/openssl/#engine-options

We of course cannot use this when we still support OpenSSL 1.x though.

Quoted 6 lines

I would be fine with supporting provider-based flows only, as it simplifies the implementation and covers my use case (OpenEmbedded integration). However, I’m concerned about compatibility with older distributions where PKCS#11 provider support may not be available by default. What would you recommend in this case?

I'm tempted to say "another person's problem". I was already not happy to contribute support for OpenSSL engines in FIT signing because it's been deprecated for years at that point but I needed it (could have kept it downstream though). We just need to make sure it's not impossible to support if someone really wants it (and it needs to work with OpenSSL 1.x I believe, even though it's official EoL you can still buy commercial support for it).

Cheers,
Quentin

#14 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

Hi Quentin,

Quoted 9 lines
Quoted 4 lines

Good point. I’ll scope this more precisely to X.509 usage. Would BINMAN_X509_PKCS11_URI be appropriate, or do you have a preferred naming convention here?

Is this really PKCS11-specific? Is there no other way to get an x509 than by PKCS11 or plaintext file? Trying to think about potentially having other providers needing something similar and then setting BINMAN_X509_PKCS11_URI for that would be confusing.

Hmmm, good point. What if we rename the variable to BINMAN_X509_KEY_URI and the entry argument to key-uri?

Quoted 10 lines
Quoted 9 lines

From my testing with SoftHSM2:

- Provider-based flow: configuring openssl.cnf is sufficient. OpenSSL dispatches "pkcs11:" URIs via the STORE API without additional CLI arguments.
- Engine-based flow: configuring the engine in openssl.cnf alone is not sufficient; "-engine pkcs11 -keyform engine" must still be passed explicitly.

Quoted 3 lines

Being curious now, I'm wondering if setting the -key to org.openssl.engine:pkcs11:<key> would be enough on OpenSSL 3.x? C.f.
https://docs.openssl.org/3.0/man1/openssl/#engine-options

Good catch! It does work.

$ OPENSSL_CONF=test_engine.cnf openssl req -new -x509 -key \
   "org.openssl.engine:pkcs11:${PKCS11_URI}" -nodes -outform DER \
   -out cert_engine_unified.der -subj "/CN=test-unified-engine" \
   -sha512 && echo "exit: $?"
exit: 0

With this, the implementation transparently supports both flows on OpenSSL 3.x - the user picks the URI form to match their setup. I'll document both URI forms in the binman documentation.

Quoted 7 lines

I'm tempted to say "another person's problem". I was already not happy to contribute support for OpenSSL engines in FIT signing because it's been deprecated for years at that point but I needed it (could have kept it downstream though). We just need to make sure it's not impossible to support if someone really wants it (and it needs to work with OpenSSL 1.x I believe, even though it's official EoL you can still buy commercial support for it).

Understood.

Regards,

Sergio Prado

#15 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

Hi Sergio,

Quoted 7 lines · Sergio Prado

Hi Quentin,

Quoted 5 lines
Quoted 4 lines

Good point. I’ll scope this more precisely to X.509 usage. Would BINMAN_X509_PKCS11_URI be appropriate, or do you have a preferred naming convention here?

Quoted 8 lines
Quoted 4 lines

Is this really PKCS11-specific? Is there no other way to get an x509 than by PKCS11 or plaintext file? Trying to think about potentially having other providers needing something similar and then setting BINMAN_X509_PKCS11_URI for that would be confusing.

Hmmm, good point. What if we rename the variable to BINMAN_X509_KEY_URI and the entry argument to key-uri?

We should have x509 in the entry argument as key-uri could mean the URI used for signing FIT images for example.

The other thing I'm worried about is "will there always be only one x509 certificate per binman invocation or can we have more".

For signing FIT images, it's pretty simple, mkimage only supports one configuration for the whole FIT last time I checked so it's not a worry as much more plumbing needs to be added to support that. Though what happens when you want to sign two FITs per binman run each with their own key... Not sure there's a usecase for that though.

Quoted 22 lines
Quoted 10 lines
Quoted 9 lines

From my testing with SoftHSM2:

- Provider-based flow: configuring openssl.cnf is sufficient. OpenSSL dispatches "pkcs11:" URIs via the STORE API without additional CLI arguments.
- Engine-based flow: configuring the engine in openssl.cnf alone is not sufficient; "-engine pkcs11 -keyform engine" must still be passed explicitly.

Quoted 3 lines

Being curious now, I'm wondering if setting the -key to org.openssl.engine:pkcs11:<key> would be enough on OpenSSL 3.x? C.f.
https://docs.openssl.org/3.0/man1/openssl/#engine-options

Good catch! It does work.

$ OPENSSL_CONF=test_engine.cnf openssl req -new -x509 -key \
    "org.openssl.engine:pkcs11:${PKCS11_URI}" -nodes -outform DER \
    -out cert_engine_unified.der -subj "/CN=test-unified-engine" \
    -sha512 && echo "exit: $?"
exit: 0
Quoted 4 lines

With this, the implementation transparently supports both flows on OpenSSL 3.x - the user picks the URI form to match their setup. I'll document both URI forms in the binman documentation.

I guess that's acceptable. I don't think we should bend backwards to support OpenSSL 1.x :)

I've realized that we have only one test for the x509-cert entry type, seems like it'd be nice to have more :) I don't think we need to make this a requirement for this series though.
We also have virtually no documentation for the arguments (they shoiuld be in the docstring of the Entry_x509_cert class), this we should fix and add the new arguments/properties to the docstring.
Finally, Entry_ti_secure and Entry_ti_secure_rom both extend Entry_x509_cert and both call super().<method> on the Entry_x509_cert mtehods so their docstring should be updated to reflect that and possibly add tests for pkcs11 to those entries as well.

Cheers,
Quentin

#16 lore raw

Re: [PATCH v3 2/2] binman: x509_cert: add PKCS#11/HSM signing support

In reply to Sergio Prado

Hi Sergio,

Quoted 31 lines · Sergio Prado

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

Allow X509 certificates used for TI K3 secure boot to be signed via an HSM using the PKCS#11 standard, so that the private key never leaves the hardware token.

Two new make variables are introduced:

BINMAN_PKCS11_URI PKCS#11 URI identifying the signing key, e.g.
pkcs11:token=mytoken;object=mykey;type=private
BINMAN_PKCS11_MODULE Path to the PKCS#11 shared library (.so), e.g.
/usr/lib/softhsm/libsofthsm2.so

When BINMAN_PKCS11_URI is set, it is forwarded to binman as the pkcs11-uri entry argument, overriding the keyfile property at signing time. BINMAN_PKCS11_MODULE is optional and only needed when the PKCS#11 library is not already configured via openssl.cnf or the PKCS11_MODULE_PATH environment variable.

The openssl bintool gains three helper methods:
[...]

Makefile | 2 +

 tools/binman/binman.rst         |  18 +++++++
 tools/binman/btool/openssl.py   | 117 ++++++++++++++++++++++++++++++++++------
 tools/binman/etype/x509_cert.py |  47 ++++++++++++++--
 tools/binman/ftest.py           | 110 +++++++++++++++++++++++++++++++++++++
 5 files changed, 274 insertions(+), 20 deletions(-)

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 91

Quoted 7 lines
tools/binman/etype/x509_cert.py +4 -0
@@ -61,6 +85,10 @@ class Entry_x509_cert(Entry_collection):
         self.key_fname = self.GetEntryArgsOrProps([
             EntryArg('keyfile', str)], required=True)[0]
         self.sw_rev = fdt_util.GetInt(self._node, 'sw-rev', 1)
+        self.pkcs11_uri = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-uri', str)], required=False)[0]
+        self.pkcs11_module = self.GetEntryArgsOrProps([
+            EntryArg('pkcs11-module', str)], required=False)[0]

keyfile is still required=True, so a user driving this from BINMAN_PKCS11_URI must also supply a dummy keyfile= on the binman command line, otherwise ReadNode() raises before the override in GetCertificate() runs. If pkcs11-uri is to be a real alternative to keyfile, one of them should be required, not both.

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 45

Quoted 7 lines
tools/binman/btool/openssl.py +5 -0
@@ -35,18 +41,89 @@ class Bintoolopenssl(bintool.Bintool):
+        if key_fname.startswith('pkcs11:'):
+            pin = os.environ.get('PKCS11_PIN')
+            if pin:
+                sep = '&' if '?' in key_fname else '?'
+                key_fname = f'{key_fname}{sep}pin-value={pin}'

Splicing pin-value=<pin> into the URI puts the cleartext PIN on openssl's argv, where any local user can read it from /proc/<pid>/cmdline or ps. Maybe that isn't critical depending on what machine it is running in. Both pkcs11-provider and the libp11 engine accept the PIN via pin-source=env:PKCS11_PIN (or OPENSSL_PIN for the provider), which keeps it out of argv - could you use one of those instead?

tools/binman/etype/x509_cert.py class Entry_x509_cert(Entry_collection): · line 113

Quoted 8 lines
tools/binman/etype/x509_cert.py +6 -0
@@ -80,6 +108,13 @@ class Entry_x509_cert(Entry_collection):
+        # Override keyfile with the PKCS#11 URI if provided. This must be
+        # done here rather than in ReadNode(), because subclasses (e.g.
+        # ti_secure_rom, ti_secure) call super().ReadNode() and then
+        # overwrite self.key_fname with the DTS 'keyfile' property.
+        if self.pkcs11_uri:
+            self.key_fname = self.pkcs11_uri

Doing the override here, in the middle of GetCertificate(), is a sign the data flow is wrong...it runs on every call and quietly changes state read by ReadNode(). I'd prefer keeping ReadNode() the single source of truth: store pkcs11_uri separately and have the openssl helper choose between key_fname and pkcs11_uri at the call site.

tools/binman/btool/openssl.py class Bintoolopenssl(bintool.Bintool): · line 41

Quoted 3 lines
tools/binman/btool/openssl.py +1 -0
@@ -35,18 +41,89 @@ class Bintoolopenssl(bintool.Bintool):
+    def _run_cmd_pkcs11(self, pkcs11_module, *args):

Threading pkcs11_module through every x509_cert_* variant (and every caller in etype/x509_cert.py) is a lot of plumbing for one piece of state that never varies within a build. Since Bintoolopenssl is a singleton per binman run, storing the module path (and uri/pin policy) on the instance once and consulting it inside the existing run_cmd path would avoid touching all four signatures and their callers.

Regards,
Simon