From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: From: Bastian Krause Date: Mon, 8 Jun 2020 10:53:05 +0200 Message-Id: <20200608085305.30964-6-bst@pengutronix.de> In-Reply-To: <20200608085305.30964-1-bst@pengutronix.de> References: <20200608085305.30964-1-bst@pengutronix.de> MIME-Version: 1.0 Subject: [ptxdist] [PATCH 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: rhi@pengutronix.de, Bastian Krause Signed-off-by: Bastian Krause --- doc/ref_code_signing_helpers.inc | 246 +++++++++++++++++++++++++++++++ doc/ref_manual.rst | 1 + 2 files changed, 247 insertions(+) create mode 100644 doc/ref_code_signing_helpers.inc diff --git a/doc/ref_code_signing_helpers.inc b/doc/ref_code_signing_helpers.inc new file mode 100644 index 000000000..cec5c9558 --- /dev/null +++ b/doc/ref_code_signing_helpers.inc @@ -0,0 +1,246 @@ +.. _code_signing_helper_functions: + +Code Signing Helper Functions +----------------------------- + +PTXdist provides various bash helper functions to be used in :ref:`code signing +providers `. +These helpers set up SoftHSM, define roles, perform PKCS#11 URI handling as +well as key and certificate authority (CA) handling. + +PTXdist stores URIs and CAs using these helpers in +``$(PTXDIST_SYSROOT_HOST)/var/lib/keys///{uri,ca.pem}``. + +.. _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_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_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_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`` + +.. _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`) + +.. _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`` diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst index 6541da3ea..e605e52a6 100644 --- a/doc/ref_manual.rst +++ b/doc/ref_manual.rst @@ -4,6 +4,7 @@ PTXdist Reference .. include:: ref_make_variables.inc .. include:: ref_make_macros.inc .. include:: ref_rule_file_layout.inc +.. include:: ref_code_signing_helpers.inc .. _ptxdist_parameter_reference: -- 2.27.0 _______________________________________________ ptxdist mailing list ptxdist@pengutronix.de To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de