From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: From: Bastian Krause Date: Fri, 12 Jun 2020 12:52:31 +0200 Message-Id: <20200612105231.4318-6-bst@pengutronix.de> In-Reply-To: <20200612105231.4318-1-bst@pengutronix.de> References: <20200612105231.4318-1-bst@pengutronix.de> MIME-Version: 1.0 Subject: [ptxdist] [PATCH v2 5/5] doc: introduce ref_code_signing_helpers List-Id: PTXdist Development Mailing List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: ptxdist@pengutronix.de Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ptxdist-bounces@pengutronix.de Sender: "ptxdist" To: ptxdist@pengutronix.de Cc: Bastian Krause , Roland Hieber Signed-off-by: Bastian Krause Reviewed-by: Roland Hieber Tested-by: Ladislav Michl --- Changes since (implicit) v1: - rebased on master - split into sections: {SoftHSM Provider,Generic Provider,Consumer} Functions - add introductory sentence for each section --- doc/ref_code_signing_helpers.rst | 264 +++++++++++++++++++++++++++++++ doc/ref_manual.rst | 1 + 2 files changed, 265 insertions(+) create mode 100644 doc/ref_code_signing_helpers.rst diff --git a/doc/ref_code_signing_helpers.rst b/doc/ref_code_signing_helpers.rst new file mode 100644 index 000000000..0f376b18c --- /dev/null +++ b/doc/ref_code_signing_helpers.rst @@ -0,0 +1,264 @@ +.. _code_signing_helper_functions: + +Code Signing Helper Functions +----------------------------- + +PTXdist provides various bash helper functions to be used in :ref:`code signing +providers ` and :ref:`code signing consumers +`. + +PTXdist stores URIs and CAs using these helpers in +``$(PTXDIST_SYSROOT_HOST)/var/lib/keys///{uri,ca.pem}``. + +SoftHSM Provider Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These helpers initialize and import public/private keys and certificates into +the SoftHSM. + +.. _cs_init_softhsm: + +cs_init_softhsm +^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_init_softhsm + +Initialize SoftHSM, and set the initial pins. + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM`` + +cs_import_cert_from_der +^^^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_import_cert_from_der + +Import certificate from a given DER file for role. +To be used with SoftHSM only. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) +- SoftHSM must have been initialized (see :ref:`cs_init_softhsm`) + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM`` + +cs_import_cert_from_pem +^^^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_import_cert_from_pem + +Import certificate from a given PEM file for role. +To be used with SoftHSM only. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) +- SoftHSM must have been initialized (see :ref:`cs_init_softhsm`) + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM``, ``HOST_OPENSSL`` + +cs_import_pubkey_from_pem +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_import_pubkey_from_pem + +Import public key from a given PEM file for role. +To be used with SoftHSM only. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) +- SoftHSM must have been initialized (see :ref:`cs_init_softhsm`) + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM``, ``HOST_OPENSSL`` + +cs_import_privkey_from_pem +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_import_privkey_from_pem + +Import private key from a given PEM file for role. +To be used with SoftHSM only. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) +- SoftHSM must have been initialized (see :ref:`cs_init_softhsm`) + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM``, ``HOST_OPENSSL`` + +cs_import_key_from_pem +^^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_import_key_from_pem + +Import private/public key pair from a given PEM file for role. +To be used with SoftHSM only. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) +- SoftHSM must have been initialized (see :ref:`cs_init_softhsm`) + +Necessary package dependencies for code signing provider: ``HOST_SOFTHSM``, ``HOST_OPENSSL`` + +Generic Provider Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These helpers allow to define roles, set PKCS#11 URIs and handle certificate +authorities (CAs). +HSM as well as SoftHSM code signing providers should use them. + +.. _cs_define_role: + +cs_define_role +^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_define_role + +Define new key role. + +A default PKCS#11 URI is set implicitly as convenience for SoftHSM use cases. + +.. _cs_set_uri: + +cs_set_uri +^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_set_uri + +Set given PKCS#11 URI for role. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) + +.. _cs_append_ca_from_pem: + +cs_append_ca_from_pem +^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_append_ca_from_pem + +Append certificate from a given PEM file for role. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) + +.. _cs_append_ca_from_der: + +cs_append_ca_from_der +^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_append_ca_from_der + +Append certificate from a given DER file for role. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) + +Necessary package dependencies for code signing provider: ``HOST_OPENSSL`` + +.. _cs_append_ca_from_uri: + +cs_append_ca_from_uri +^^^^^^^^^^^^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_append_ca_from_uri [] + +Append certificate from a given PKCS#11 URI for role. +If URI is omitted the already set URI for role is used. + +Preconditions: + +- the role must have been defined (see :ref:`cs_define_role`) + +Necessary package dependencies for code signing provider: ``HOST_OPENSSL``, ``HOST_EXTRACT_CERT`` + +Consumer Functions +~~~~~~~~~~~~~~~~~~ + +Packages that want to sign something or need access to keys/CAs can retrieve +PKCS#11 URIs and CAs with these helpers. + +.. _cs_get_uri: + +cs_get_uri +^^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_get_uri + +Get PKCS#11 URI for role. + +Preconditions: + +- the URI must have been set (see :ref:`cs_set_uri`) + +.. _cs_get_ca: + +cs_get_ca +^^^^^^^^^ + +Usage: + +.. code-block:: bash + + cs_get_ca + +Get path to the CA in PEM format for role. + +Preconditions: + +- a certificate must have been appended to the CA + (see :ref:`cs_append_ca_from_pem`, :ref:`cs_append_ca_from_der`, + :ref:`cs_append_ca_from_uri`) diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst index 850d72399..dea1610c6 100644 --- a/doc/ref_manual.rst +++ b/doc/ref_manual.rst @@ -7,3 +7,4 @@ PTXdist Reference ref_make_macros ref_rule_file_layout ref_parameter + ref_code_signing_helpers -- 2.27.0 _______________________________________________ ptxdist mailing list ptxdist@pengutronix.de To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de