[ptxdist] [PATCH v3 2/5] ptxd_lib_code_signing: introduce role groups

[Roland Hieber <rhi@pengutronix.de>]

From: Marc Kleine-Budde <mkl@pengutronix.de>

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>
---
PATCH v3:
 - no changes

PATCH v2 (rhi): https://lore.ptxdist.org/ptxdist/20210627231121.28313-2-rhi@pengutronix.de
 - reorder from PATCH 1/n to PATCH 2/n
 - be more concise and call the new concept "role groups" instead of the
   (less expressive) "code signing groups" or "key groups"
 - add API docs for new shell functions (feedback from myself)
 - rephrase and fix typos in commit message

PATCH v1 (mkl): https://lore.ptxdist.org/ptxdist/20210412161900.2376802-1-mkl@pengutronix.de
---
 doc/dev_code_signing.rst             |  5 ++
 doc/ref_code_signing_helpers.rst     | 79 ++++++++++++++++++++++++++++
 scripts/lib/ptxd_lib_code_signing.sh | 45 ++++++++++++++++
 3 files changed, 129 insertions(+)

diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst
index 56ac0e3b3217..1f43f2b60ade 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 f7928f52ebef..99a395b287c9 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
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/scripts/lib/ptxd_lib_code_signing.sh b/scripts/lib/ptxd_lib_code_signing.sh
index 199f679ef828..c1c61e063b6c 100644
--- a/scripts/lib/ptxd_lib_code_signing.sh
+++ b/scripts/lib/ptxd_lib_code_signing.sh
@@ -99,6 +99,51 @@ cs_define_role() {
 }
 export -f cs_define_role
 
+#
+# cs_define_group <group>
+#
+# Define a new role group.
+#
+cs_define_group() {
+    local group="${1}"
+    cs_init_variables
+
+    mkdir -p "${keydir}/${group}.group" &&
+    rm -f "${keydir}/${group}.group/roles"
+}
+export -f cs_define_group
+
+#
+# cs_group_add_roles <group> <role> ... <role>
+#
+# Set the roles for a group
+#
+cs_group_add_roles() {
+    local group="${1}"
+    shift
+    cs_init_variables
+
+    local orig_IFS="${IFS}"
+    IFS="
+"
+    echo "${*}" >> "${keydir}/${group}.group/roles" &&
+    IFS=${orig_IFS}
+}
+export -f cs_group_add_roles
+
+#
+# cs_group_get_roles <group>
+#
+# Gets the roles of a group
+#
+cs_group_get_roles() {
+    local group="${1}"
+    cs_init_variables
+
+    cat "${keydir}/${group}.group/roles"
+}
+export -f cs_group_get_roles
+
 #
 # cs_set_uri <role> <uri>
 #
-- 
2.30.2


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de
To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de