k3-binman ergonomics
v2 cover k3-binman ergonomics
When trying to hook up use of a customer's own signing infrastructure for some am62x devices, I found it was more difficult than it should be to point at the right key(s). One has to patch in the keyfile= property in way too many places, and if you miss just one, the build succeeds using the generic custMpk.pem for the one you missed, but of course the resulting artifacts are unbootable.
Use the template mechanism that binman already has to allow one to only set the keyfile= in a single place. I cannot really imagine any case where one would not want to use the same key for signing all artifacts across the r5/a53 cores, but that is of course still possible, just as any downstreams that have explicit
&{/binman/tiboot3-am62x-hs-evm.bin/ti-secure-rom} {
keyfile = "foobar.pem";
};&{/binman/tiboot3-am62x-hs-fs-evm.bin/ti-secure-rom} {
keyfile = "foobar.pem";
};will continue to work.
Changes in v2:
- Make sure an x509_cert entry (and derived classes) always has _some_ valid reg_dist_name attribute. openssl not only requires existence of a distinguish name section, it also needs to be non-empty.
- Implement the "allow string list a value" for distinguished-name properties alluded to in v1, as it might as well be done now and doesn't take a lot of code.
- Verify that property values in the distinguished-name node are strings or string lists.
- Add documentation, both to the binman entry definitions and a new patch with an update of k3.rst's section on Secure Boot.
v1: https://lore.kernel.org/u-boot/[email protected]/
Rasmus Villemoes (7):
binman: openssl: refactor creation of Distinguished Name section from
dict
binman: x509_cert: allow and parse distinguished-name subnode
binman: x509: fix CN emitted for basic x509 certificates k3-binman.dtsi: add keyfile_template node
k3-binman.dtsi: add empty distinguished_name_template k3-binman.dtsi: insert keyfile and distinguished name templates in all
ti-secure(-rom) nodes
doc: k3.rst: describe use of keyname and distinguished_name binman
templates
arch/arm/dts/k3-binman.dtsi | 35 ++++++++---- doc/board/ti/k3.rst | 48 +++++++++++++++++ tools/binman/btool/openssl.py | 68 ++++++++++++------------ tools/binman/etype/ti_secure.py | 16 +++--- tools/binman/etype/ti_secure_rom.py | 16 +++--- tools/binman/etype/x509_cert.py | 23 ++++++-- tools/binman/test/security/x509_cert.dts | 5 +- 7 files changed, 147 insertions(+), 64 deletions(-)
Signature · 1 line
2.55.0
PATCH v2 1/7 binman: openssl: refactor creation of Distinguished Name section from dict
Instead of manually expanding the req_dist_name_dict, create a helper function for creating a config section from any dict. That will also automatically allow other fields to be emitted.
We can allow a field with multiple values, e.g. "OU" -> ["First OU", "Second OU"], and encode that in the config file using
1.OU = First OU
2.OU = Second OU
as documented in 'man 5 config'.
--- tools/binman/btool/openssl.py | 58 +++++++++++++++++------------------ 1 file changed, 28 insertions(+), 30 deletions(-)
tools/binman/btool/openssl.py +28 -30
@@ -36,6 +36,28 @@ class Bintoolopenssl(bintool.Bintool): name, 'openssl cryptography toolkit', version_regex=r'OpenSSL (.*) \(', version_args='version') + @staticmethod + def dict_to_config_section(section_name, data): + """Generate a section for an openssl config file from key-value pairs + + Args: + section_name: The name of the section + data: dict containing key-value pairs + + Returns: + A multi-line string containing the section definition. + + Each key must be a string, each value can be a string or a list of strings. + """ + sec = f'[ {section_name} ]\n' + for field, value in data.items(): + if isinstance(value, str): + sec += f'{field:22s} = {value}\n' + elif isinstance(value, list): + for i, s in enumerate(value): + sec += f'{i+1}.{field:20s} = {s}\n' + return sec + def x509_cert(self, cert_fname, input_fname, key_fname, cn, revision, config_fname): """Create a certificate
@@ -92,8 +114,7 @@ imageSize = INTEGER:{len(indata)} sw_rev (int): Software revision config_fname (str): Filename to write fconfig into req_dist_name_dict (dict): Dictionary containing key-value pairs of - req_distinguished_name section extensions, must contain extensions for - C, ST, L, O, OU, CN and emailAddress + req_distinguished_name section extensions firewall_cert_data (dict): - auth_in_place (int): The Priv ID for copying as the specific host in firewall protected region
@@ -114,14 +135,7 @@ x509_extensions = v3_ca prompt = no dirstring_type = nobmp -[ req_distinguished_name ] -C = {req_dist_name_dict['C']} -ST = {req_dist_name_dict['ST']} -L = {req_dist_name_dict['L']} -O = {req_dist_name_dict['O']} -OU = {req_dist_name_dict['OU']} -CN = {req_dist_name_dict['CN']} -emailAddress = {req_dist_name_dict['emailAddress']} +{self.dict_to_config_section('req_distinguished_name', req_dist_name_dict)} [ v3_ca ] basicConstraints = CA:true
@@ -163,8 +177,7 @@ numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']} sw_rev (int): Software revision config_fname (str): Filename to write fconfig into req_dist_name_dict (dict): Dictionary containing key-value pairs of - req_distinguished_name section extensions, must contain extensions for - C, ST, L, O, OU, CN and emailAddress + req_distinguished_name section extensions cert_type (int): Certification type bootcore (int): Booting core bootcore_opts(int): Booting core option, lockstep (0) or split (2) mode
@@ -184,14 +197,7 @@ numFirewallRegions = INTEGER:{firewall_cert_data['num_firewalls']} prompt = no dirstring_type = nobmp - [ req_distinguished_name ] -C = {req_dist_name_dict['C']} -ST = {req_dist_name_dict['ST']} -L = {req_dist_name_dict['L']} -O = {req_dist_name_dict['O']} -OU = {req_dist_name_dict['OU']} -CN = {req_dist_name_dict['CN']} -emailAddress = {req_dist_name_dict['emailAddress']} +{self.dict_to_config_section('req_distinguished_name', req_dist_name_dict)} [ v3_ca ] basicConstraints = CA:true
@@ -252,8 +258,7 @@ emailAddress = {req_dist_name_dict['emailAddress']} sw_rev (int): Software revision config_fname (str): Filename to write fconfig into req_dist_name_dict (dict): Dictionary containing key-value pairs of - req_distinguished_name section extensions, must contain extensions for - C, ST, L, O, OU, CN and emailAddress + req_distinguished_name section extensions cert_type (int): Certification type bootcore (int): Booting core load_addr (int): Load address of image
@@ -274,14 +279,7 @@ x509_extensions = v3_ca prompt = no dirstring_type = nobmp -[ req_distinguished_name ] -C = {req_dist_name_dict['C']} -ST = {req_dist_name_dict['ST']} -L = {req_dist_name_dict['L']} -O = {req_dist_name_dict['O']} -OU = {req_dist_name_dict['OU']} -CN = {req_dist_name_dict['CN']} -emailAddress = {req_dist_name_dict['emailAddress']} +{self.dict_to_config_section('req_distinguished_name', req_dist_name_dict)} [ v3_ca ] basicConstraints = CA:true
Signature · 1 line
2.55.0
PATCH v2 2/7 binman: x509_cert: allow and parse distinguished-name subnode
In reply to Rasmus VillemoesCurrently, the ti-secure and ti-secure-rom types hardcode the contents of the Distinguished Name section. Those values are not necessarily appropriate for all boards that just happen to include a SOC produced by TI.
Allow placing a distinguished-name subnode inside the binman node representing the Entry_x509_cert (or derived classes), and if present, use that information.
Ensure an Entry_x509_cert instance always has some non-empty req_dist_name dict by adding a dummy default (because for the certificate generation there must be a non-empty req_dist_name section), and let derived classes provide their own default.
--- tools/binman/etype/ti_secure.py | 16 +++++++++------- tools/binman/etype/ti_secure_rom.py | 16 +++++++++------- tools/binman/etype/x509_cert.py | 20 +++++++++++++++++++- 3 files changed, 37 insertions(+), 15 deletions(-)
tools/binman/etype/ti_secure.py +9 -7
@@ -58,6 +58,7 @@ class Entry_ti_secure(Entry_x509_cert): - Lower Byte - Remains 0x02 as per our use case ( 0x02: Move the authenticated binary back to the header ) - Upper Byte - The Host ID of the core owning the firewall + - distinguished-name: See :ref:`etype_x509_cert` Output files: - input.<unique_name> - input file passed to openssl
@@ -99,6 +100,14 @@ class Entry_ti_secure(Entry_x509_cert): writes the signature in this entry. This allows verification that the data is genuine. """ + default_dist_name = {'C': 'US', + 'ST': 'TX', + 'L': 'Dallas', + 'O': 'Texas Instruments Incorporated', + 'OU': 'Processors', + 'CN': 'TI Support', + 'emailAddress': '[email protected]'} + def __init__(self, section, etype, node): super().__init__(section, etype, node) self.openssl = None
@@ -117,13 +126,6 @@ class Entry_ti_secure(Entry_x509_cert): self.firewall_cert_data['auth_in_place'] = auth_in_place self.ReadFirewallNode() self.sha = fdt_util.GetInt(self._node, 'sha', 512) - self.req_dist_name = {'C': 'US', - 'ST': 'TX', - 'L': 'Dallas', - 'O': 'Texas Instruments Incorporated', - 'OU': 'Processors', - 'CN': 'TI Support', - 'emailAddress': '[email protected]'} self.debug = fdt_util.GetBool(self._node, 'debug', False) def ReadFirewallNode(self):
tools/binman/etype/ti_secure_rom.py +9 -7
@@ -33,6 +33,7 @@ class Entry_ti_secure_rom(Entry_x509_cert): - content: phandle of SPL in case of legacy bootflow or phandles of component binaries in case of combined bootflow - core-opts (optional): lockstep (0) or split (2) mode set to 0 by default + - distinguished-name: See :ref:`etype_x509_cert` The following properties are only for generating a combined bootflow binary: - sysfw-inner-cert: boolean if binary contains sysfw inner certificate
@@ -58,6 +59,14 @@ class Entry_ti_secure_rom(Entry_x509_cert): writes the signature in this entry. This allows verification that the data is genuine. """ + default_dist_name = {'C': 'US', + 'ST': 'TX', + 'L': 'Dallas', + 'O': 'Texas Instruments Incorporated', + 'OU': 'Processors', + 'CN': 'TI Support', + 'emailAddress': '[email protected]'} + def __init__(self, section, etype, node): super().__init__(section, etype, node) self.openssl = None
@@ -80,13 +89,6 @@ class Entry_ti_secure_rom(Entry_x509_cert): self.dm_data = fdt_util.GetBool(self._node, 'dm-data', False) if self.dm_data: self.load_addr_dm_data = fdt_util.GetInt(self._node, 'load-dm-data', 0x00000000) - self.req_dist_name = {'C': 'US', - 'ST': 'TX', - 'L': 'Dallas', - 'O': 'Texas Instruments Incorporated', - 'OU': 'Processors', - 'CN': 'TI Support', - 'emailAddress': '[email protected]'} self.debug = fdt_util.GetBool(self._node, 'debug', False) def NonCombinedGetCertificate(self, required):
tools/binman/etype/x509_cert.py +19 -1
@@ -19,6 +19,11 @@ class Entry_x509_cert(Entry_collection): Properties / Entry arguments: - content: List of phandles to entries to sign + - distinguished-name: Optional subnode containing key-value + pairs used for the Distinguished Name in the generated + certificate. Property names must be valid fields (e.g. 'CN', + 'L', 'OU'), and their values must either be strings or + string lists. Output files: - input.<unique_name> - input file passed to openssl
@@ -28,10 +33,13 @@ 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 """ + + default_dist_name = {'CN': 'Firmware Signature'} + def __init__(self, section, etype, node): super().__init__(section, etype, node) self.openssl = None - self.req_dist_name = None + self.req_dist_name = self.default_dist_name self.cert_type = None self.bootcore = None self.bootcore_opts = None
@@ -61,6 +69,16 @@ 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) + dist_name_node = self._node.FindNode('distinguished-name') + if dist_name_node: + self.req_dist_name = dict() + for pname, prop in dist_name_node.props.items(): + val = prop.value + if not (isinstance(val, str) or + (isinstance(val, list) and all(isinstance(x, str) for x in val))): + self.Raise(f"Invalid value for property {pname} in distinguished-name node, " + "must be string or string list") + self.req_dist_name[pname] = val def GetCertificate(self, required, type='generic'): """Get the contents of this entry
Signature · 1 line
2.55.0
PATCH v2 3/7 binman: x509: fix CN emitted for basic x509 certificates
In reply to Rasmus VillemoesI'm pretty sure it was never the intention to emit the output filename (cert_fname) as the value of the CN distinguished name.
The cert-ca property was parsed from the dts node, stored in ._cert_ca, passed on as the cn argument to x509_cert(), but then not used at all.
Now that we always read a distinguished-name subnode if present, use that method instead.
--- tools/binman/btool/openssl.py | 10 +++++----- tools/binman/etype/x509_cert.py | 3 +-- tools/binman/test/security/x509_cert.dts | 5 ++++- 3 files changed, 10 insertions(+), 8 deletions(-)
tools/binman/btool/openssl.py +5 -5
@@ -58,15 +58,16 @@ class Bintoolopenssl(bintool.Bintool): sec += f'{i+1}.{field:20s} = {s}\n' return sec - def x509_cert(self, cert_fname, input_fname, key_fname, cn, revision, - config_fname): + def x509_cert(self, cert_fname, input_fname, key_fname, req_dist_name_dict, + revision, config_fname): """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 - cn (str): Common name + req_dist_name_dict (dict): Contents of req_distinguished_name section + in generated openssl config file revision (int): Revision number config_fname (str): Filename to write fconfig into
@@ -82,8 +83,7 @@ x509_extensions = v3_ca prompt = no dirstring_type = nobmp -[ req_distinguished_name ] -CN = {cert_fname} +{self.dict_to_config_section('req_distinguished_name', req_dist_name_dict)} [ v3_ca ] basicConstraints = CA:true
tools/binman/etype/x509_cert.py +1 -2
@@ -64,7 +64,6 @@ class Entry_x509_cert(Entry_collection): def ReadNode(self): super().ReadNode() - self._cert_ca = fdt_util.GetString(self._node, 'cert-ca') self._cert_rev = fdt_util.GetInt(self._node, 'cert-revision-int', 0) self.key_fname = self.GetEntryArgsOrProps([ EntryArg('keyfile', str)], required=True)[0]
@@ -109,7 +108,7 @@ class Entry_x509_cert(Entry_collection): cert_fname=output_fname, input_fname=input_fname, key_fname=self.key_fname, - cn=self._cert_ca, + req_dist_name_dict=self.req_dist_name, revision=self._cert_rev, config_fname=config_fname) elif type == 'sysfw':
tools/binman/test/security/x509_cert.dts +4 -1
@@ -8,9 +8,12 @@ binman { x509-cert { - cert-ca = "IOT2050 Firmware Signature"; cert-revision-int = <0>; content = <&u_boot>; + + distinguished-name { + CN = "IOT2050 Firmware Signature"; + }; }; u_boot: u-boot {
Signature · 1 line
2.55.0
PATCH v2 4/7 k3-binman.dtsi: add keyfile_template node
In reply to Rasmus VillemoesCurrently, it is somewhat tedious for downstream/custom boards to override the keyfile used for signing all the various artifacts involved in booting on K3 devices to point at their own key. For a key stored in a file, one could override node which "generates" (copies) custMpk.pem in the build dir from the one in the source dir and point that at another filename=. That works, but is a little misleading.
However, when the "keyfile" needs to be, say, a pkcs#11 uri, one has to have overrides in one's .dtsi for each and every ti-secure / ti-secure-rom node, and a lot of those do not even have dts labels, so one has to use their full /binman/... path.
Add a small dedicated template that only contains the keyfile property. In a subsequent patch, we will change nodes that contain an explicit 'keyfile = "custMpk.pem"' to instead have this template inserted. This way, the downstream board's .dtsi file only needs to contain something like
&keyfile_template {
keyfile = "pkcs11:object=my-key-identifier";
};and that will then automatically propagate to all the nodes.
--- arch/arm/dts/k3-binman.dtsi | 4 ++++ 1 file changed, 4 insertions(+)
arch/arm/dts/k3-binman.dtsi +4 -0
@@ -25,6 +25,10 @@ filename = "arch/arm/mach-k3/keys/ti-degenerate-key.pem"; }; }; + + keyfile_template: template-keyfile { + keyfile = "custMpk.pem"; + }; }; #ifndef CONFIG_ARM64
Signature · 1 line
2.55.0
PATCH v2 5/7 k3-binman.dtsi: add empty distinguished_name_template
In reply to Rasmus VillemoesWith the previous commit, "binman: x509_cert: allow and parse distinguished-name subnode", it is possible for downstream boards to put more appropriate values in the req_distinguished_name section in the certificate being generated than the hard-coded TI values. However, that requires adding a distinguished-name section to each and every ti-secure or ti-secure-rom binman node.
In order to avoid lots of repetition and make it easier to just add the information in one place, add an empty template-dist-name template which we can inject in every such binman node. That makes no difference for existing boards, but makes it possible for downstream boards to simply do
&distinguished_name_template {
distinguished-name {
C = "DK";
...
};
};in their -u-boot.dtsi.
--- arch/arm/dts/k3-binman.dtsi | 10 ++++++++++ 1 file changed, 10 insertions(+)
arch/arm/dts/k3-binman.dtsi +10 -0
@@ -29,6 +29,16 @@ keyfile_template: template-keyfile { keyfile = "custMpk.pem"; }; + + distinguished_name_template: template-dist-name { + /* + * Empty, but allows downstreams to inject a + * distinguished-name subnode with appropriate + * contents from their -u-boot.dtsi, which will + * propagate to all ti-secure(-rom) nodes including + * this template. + */ + }; }; #ifndef CONFIG_ARM64
Signature · 1 line
2.55.0
PATCH v2 6/7 k3-binman.dtsi: insert keyfile and distinguished name templates in all ti-secure(-rom) nodes
In reply to Rasmus VillemoesThis should not make any functional difference, and downstream boards that already override the keyfile property via an explicit .dtsi fragment for each node will continue to have precedence over the value coming from the template. But this makes it much more ergonomic to have the keyfile and distinguished-name have consistent values throughout, because one only has to override the values in the templates and not each and every individual node.
--- arch/arm/dts/k3-binman.dtsi | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-)
arch/arm/dts/k3-binman.dtsi +10 -11
@@ -150,8 +150,8 @@ arch = "arm"; compression = "none"; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&board_cfg>; - keyfile = "custMpk.pem"; }; board_cfg: board-cfg { filename = "board-cfg.bin";
@@ -165,8 +165,8 @@ arch = "arm"; compression = "none"; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&pm_cfg>; - keyfile = "custMpk.pem"; }; pm_cfg: pm-cfg { filename = "pm-cfg.bin";
@@ -179,8 +179,8 @@ arch = "arm"; compression = "none"; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&rm_cfg>; - keyfile = "custMpk.pem"; }; rm_cfg: rm-cfg { filename = "rm-cfg.bin";
@@ -193,8 +193,8 @@ arch = "arm"; compression = "none"; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&sec_cfg>; - keyfile = "custMpk.pem"; }; sec_cfg: sec-cfg { filename = "sec-cfg.bin";
@@ -287,8 +287,8 @@ load = <CONFIG_K3_ATF_LOAD_ADDR>; entry = <CONFIG_K3_ATF_LOAD_ADDR>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&atf>; - keyfile = "custMpk.pem"; }; atf: atf-bl31 { };
@@ -303,8 +303,8 @@ load = <CONFIG_K3_OPTEE_LOAD_ADDR>; entry = <CONFIG_K3_OPTEE_LOAD_ADDR>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&tee>; - keyfile = "custMpk.pem"; }; tee: tee-os { optional;
@@ -330,9 +330,8 @@ load = <CONFIG_SPL_TEXT_BASE>; entry = <CONFIG_SPL_TEXT_BASE>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&u_boot_spl_nodtb>; - keyfile = "custMpk.pem"; - }; u_boot_spl_nodtb: blob-ext { filename = "spl/u-boot-spl-nodtb.bin";
@@ -419,8 +418,8 @@ compression = "none"; load = <CONFIG_TEXT_BASE>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&u_boot_nodtb>; - keyfile = "custMpk.pem"; }; u_boot_nodtb: u-boot-nodtb { };
@@ -521,8 +520,8 @@ load = <CONFIG_K3_ATF_LOAD_ADDR>; entry = <CONFIG_K3_ATF_LOAD_ADDR>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&atf_falcon>; - keyfile = "custMpk.pem"; }; atf_falcon: atf-bl31 { };
@@ -536,8 +535,8 @@ load = <CONFIG_K3_OPTEE_LOAD_ADDR>; entry = <CONFIG_K3_OPTEE_LOAD_ADDR>; ti-secure { + insert-template = <&keyfile_template>, <&distinguished_name_template>; content = <&tee_falcon>; - keyfile = "custMpk.pem"; }; tee_falcon: tee-os { optional;
Signature · 1 line
2.55.0
PATCH v2 7/7 doc: k3.rst: describe use of keyname and distinguished_name binman templates
In reply to Rasmus VillemoesDocument how one can use the keyname_template to specify one's own key in a single place, and similarly document the use of the distinguished_name_template.
Also mention the ability to use a pkcs#11 uri as "keyfile", and that it requires one to provide a suitable openssl configuration file (via the OPENSSL_CONF environment variable). Details on how to write such a file for one's specific provider is out of scope for this document.
--- doc/board/ti/k3.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+)
doc/board/ti/k3.rst +48 -0
@@ -127,6 +127,54 @@ function as in HS-SE, but as there are no customer keys to verify the signatures against, the authentication will pass for certificates signed with any key. +In order to direct the build to use your own signing infrastructure +instead of the custMpk.pem dummy key shipped with the U-Boot sources, +add something like + +.. code-block:: dts + + &keyname_template { + keyfile = "/path/to/your/key.pem"; + }; + +to your board's ``-u-boot.dtsi`` file. You can also customize the +Distinguished Name in the generated certificates by including +something like + +.. code-block:: dts + + &distinguished_name_template { + distinguished-name { + C = "DE"; + L = "Berlin"; + O = "Acme Corporation"; + OU = "Cartoon props"; + }; + }; + +Ensure that any ``ti-secure`` or ``ti-secure-rom`` nodes defined in +your own ``.dts`` files contain + +.. code-block:: dts + + insert-template = <&keyfile_template>, <&distinguished_name_template>; + +as that will ensure that all certificates use the key and +Distinguished Name defined in the templates. + +If you do not have the private key in a file, but instead use a HSM of +some sort, it is also possible to set ``keyfile`` to a PKCS#11 URI, e.g. + +.. code-block:: dts + + &keyname_template { + keyfile = "pkcs11:object=your-key-identifier"; + }; + +For that to work, you must set the ``OPENSSL_CONF`` environment +variable appropriately when building, pointing it at a configuration +file matching your pkcs#11 provider. + Chain of trust ^^^^^^^^^^^^^^
Signature · 1 line
2.55.0