ptxd_lib_code_signing: introduce role groups

A role group consists of one or more roles. It should be used where more
than one role is needed, but the exact names and/or number of roles
depend on the used code signing provider.

For example the generation of the imx HABv4 fuse table can use 1 to 4
SRK keys as input. If the signing provider is an HSM, the current
mechanism with continuous numbered URI may not work – role groups to the
rescue.

To make use of role groups, define roles as usual:

| r="imx-habv4-srk1"
| cs_define_role "${r}"
| cs_set_uri "${r}" "pkcs11:object=SRK CA 0"
| cs_append_ca_from_uri "${r}"
|
| r="imx-habv4-srk2"
| cs_define_role "${r}"
| cs_set_uri "${r}" "pkcs11:object=SRK CA 1"
| cs_append_ca_from_uri "${r}"

Now define a role group and add the roles to the group:

| g="imx-habv4-srk"
| cs_define_group "${g}"
| cs_group_add_roles "${g}" "imx-habv4-srk1" "imx-habv4-srk2"

Use the function cs_group_get_roles() to get the roles of a group.

In a later patch the function ptxd_make_imx_habv4_gen_table() is
converted to make use $(cs_group_get_roles imx-habv4-srk) to get the
roles of the imx-habv4-srk group.

Co-authored-by: Roland Hieber <rhi@pengutronix.de>
Signed-off-by: Marc Kleine-Budde <mkl@pengutronix.de>
Signed-off-by: Roland Hieber <rhi@pengutronix.de>
Message-Id: <20210708203941.30212-2-rhi@pengutronix.de>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

2 files changed, 84 insertions, 0 deletions

diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst
index 56ac0e3b3..1f43f2b60 100644
--- a/doc/dev_code_signing.rst
+++ b/doc/dev_code_signing.rst
@@ -19,6 +19,11 @@ development) the URIs are usually not hardcoded in the package configuration.
 Instead, PTXdist has the idea of **roles** which are string identifiers used to
 access a single private/public key pair and a certificate.
 
+Roles can be grouped into **role groups**.
+Role groups should be used where more than one role is needed, but the exact
+names and/or number of roles depend on the concrete code signing provider.
+For example, an i.MX HABv4 fuse table can contain up to four keys.
+
 Finally, one or several **code signing providers** supply the mapping from
 roles to the respective key material or even provide it themselves for
 development.
diff --git a/doc/ref_code_signing_helpers.rst b/doc/ref_code_signing_helpers.rst
index f7928f52e..99a395b28 100644
--- a/doc/ref_code_signing_helpers.rst
+++ b/doc/ref_code_signing_helpers.rst
@@ -215,6 +215,85 @@ Preconditions:
 - when used with SoftHSM, certificates must have been imported before
   (see :ref:`cs_import_cert_from_der`, :ref:`cs_import_cert_from_pem`)
 
+.. _cs_define_group:
+
+cs_define_group
+^^^^^^^^^^^^^^^
+
+Usage:
+
+.. code-block:: bash
+
+   cs_define_group <group>
+
+Define a new role group.
+
+See :ref:`cs_group_add_roles` for an example.
+
+.. _cs_group_add_roles:
+
+cs_group_add_roles
+^^^^^^^^^^^^^^^^^^
+
+Usage:
+
+.. code-block:: bash
+
+   cs_group_add_roles <group> <roles...>
+
+Add all given roles to a role group.
+
+Preconditions:
+
+- the group must have been defined (see :ref:`cs_define_group`)
+- the role(s) must have been defined (see :ref:`cs_define_role`)
+
+Example:
+
+.. code-block:: bash
+
+   # define two roles named imx-habv4-srk1 and imx-habv4-srk2
+   r="imx-habv4-srk1"
+   cs_define_role "${r}"
+   cs_set_uri "${r}" "pkcs11:object=SRK CA 0"
+   cs_append_ca_from_uri "${r}"
+   r="imx-habv4-srk2"
+   cs_define_role "${r}"
+   cs_set_uri "${r}" "pkcs11:object=SRK CA 1"
+   cs_append_ca_from_uri "${r}"
+
+   # define a group and add the roles
+   g="imx-habv4-srk"
+   cs_define_group "${g}"
+   cs_group_add_roles "${g}" "imx-habv4-srk1" "imx-habv4-srk2"
+
+.. _cs_group_get_roles:
+
+cs_group_get_roles
+^^^^^^^^^^^^^^^^^^
+
+Usage:
+
+.. code-block:: bash
+
+   cs_group_get_roles <group>
+
+Get a list of all roles that have been added to the role group.
+
+Example:
+
+.. code-block:: bash
+
+   # iterate over role names in a role group, and print their name and URI
+   for role in $(cs_group_get_roles "imx-habv4-srk"); do
+   	echo "role '${role}' has URI '$(cs_get_uri "${role}")'"
+   done
+
+In the example given in :ref:`cs_group_add_roles` above, this would print::
+
+   role 'imx-habv4-srk1' has URI 'pkcs11:object=SRK CA 0'
+   role 'imx-habv4-srk2' has URI 'pkcs11:object=SRK CA 1'
+
 Consumer Functions
 ~~~~~~~~~~~~~~~~~~