From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: From: Bastian Krause Date: Fri, 12 Jun 2020 12:52:29 +0200 Message-Id: <20200612105231.4318-4-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 3/5] doc: move code signing docs from scripts/ into doc/ 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 --- No changes since (implicit) v1. --- doc/dev_code_signing.rst | 36 ++++++++++++++++++++++++++++ doc/dev_manual.rst | 1 + scripts/lib/ptxd_lib_code_signing.sh | 32 ++----------------------- 3 files changed, 39 insertions(+), 30 deletions(-) create mode 100644 doc/dev_code_signing.rst diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst new file mode 100644 index 000000000..de0087f8b --- /dev/null +++ b/doc/dev_code_signing.rst @@ -0,0 +1,36 @@ +.. _code_signing: + +Code Signing +------------ + +This is an overview over the ptxdist signing infrastructure. +ptxdist uses PKCS#11 internally for providing access to keys and certificates. +Packages that wish to sign something should implement a PKCS#11 interface. + +As PKCS#11 URIs usually differ between different usecases (release vs. +development) the URIs normally are 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. + +ptxdist supports Hardware Security Modules (HSM). +In case a HSM is not present or shall not be used SoftHSM is used internally to +transparently provide the same API internally. + +For each role a PKCS#11 URI must be known by ptxdist. +In case of a HSM the keys and certificates are stored in the HSM, but ptxdist +needs to know the PKCS#11 URI to access the keys. +This is done in ptxdist rule files calling cs_set_uri . +For SoftHSM the URI is generated internally by ptxdist, but instead the +keys/certificates for each role have have to be imported. +This is done with the cs_import_* functions below. + +During each invocation of ptxdist exactly one key provider is active. +The code signing provider can be chosen with the PTXCONF_CODE_SIGNING_PROVIDER +variable. +A code signing provider is a package resposible for providing the role <-> +PKCS#11 URI relationships in case a HSM is used or for providing the key +material in case SoftHSM is used. + +A package which wants to sign something or which needs access to keys has to +select CODE_SIGNING. +This makes sure the keys are ready when the package is being built. diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst index 47a77a9be..03a05a661 100644 --- a/doc/dev_manual.rst +++ b/doc/dev_manual.rst @@ -14,3 +14,4 @@ This chapter shows all (or most) of the details of how PTXdist works. dev_add_bin_only_files dev_create_new_pkg_templates dev_layers_in_ptxdist + dev_code_signing diff --git a/scripts/lib/ptxd_lib_code_signing.sh b/scripts/lib/ptxd_lib_code_signing.sh index a7779f821..34d7251fd 100644 --- a/scripts/lib/ptxd_lib_code_signing.sh +++ b/scripts/lib/ptxd_lib_code_signing.sh @@ -7,36 +7,8 @@ # # -# This is an overview over the ptxdist signing infrastructure. ptxdist -# uses PKCS#11 internally for providing access to keys and certificates. -# Packages that wish to sign something should implement a PKCS#11 interface. -# -# As PKCS#11 URIs usually differ between different usecases (release vs. -# development) the URIs normally are 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. -# -# ptxdist supports Hardware Security Modules (HSM). In case a HSM is not -# present or shall not be used SoftHSM is used internally to transparently -# provide the same API internally. -# -# For each role a PKCS#11 URI must be known by ptxdist. In case of a HSM -# the keys and certificates are stored in the HSM, but ptxdist needs to know -# the PKCS#11 URI to access the keys. This is done in ptxdist rule files -# calling cs_set_uri . For SoftHSM the URI is generated internally -# by ptxdist, but instead the keys/certificates for each role have have to -# be imported. This is done with the cs_import_* functions below. -# -# During each invocation of ptxdist exactly one key provider is active. The -# code signing provider can be chosen with the PTXCONF_CODE_SIGNING_PROVIDER -# variable. A code signing provider is a package resposible for providing -# the role <-> PKCS#11 URI relationships in case a HSM is used or for providing -# the key material in case SoftHSM is used. -# -# A package which wants to sign something or which needs access to keys has -# to select CODE_SIGNING. This makes sure the keys are ready when the package -# is being built. +# See doc/dev_code_signing.inc for documentation about ptxdist's code signing +# infrastructure. # cs_check_env() { -- 2.27.0 _______________________________________________ ptxdist mailing list ptxdist@pengutronix.de To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de