From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: In-Reply-To: <20200617143125.23999-5-bst@pengutronix.de> MIME-Version: 1.0 Message-Id: From: Michael Olbrich Date: Sat, 20 Jun 2020 00:04:08 +0200 Subject: Re: [ptxdist] [APPLIED] 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 Thanks, applied as 33c4b37cab1ba5ae924e073d65ab0cbfa2b7c922. Michael [sent from post-receive hook] On Sat, 20 Jun 2020 00:04:08 +0200, Bastian Krause wrote: > Signed-off-by: Bastian Krause > Reviewed-by: Roland Hieber > Tested-by: Ladislav Michl > Message-Id: <20200617143125.23999-5-bst@pengutronix.de> > Signed-off-by: Michael Olbrich > > diff --git a/doc/dev_code_signing.rst b/doc/dev_code_signing.rst > new file mode 100644 > index 000000000000..de0087f8b36a > --- /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 47a77a9be62f..03a05a661a97 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 a7779f8212c6..65ce62dd0a32 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.rst for documentation about PTXdist's code signing > +# infrastructure. > # > > cs_check_env() { _______________________________________________ ptxdist mailing list ptxdist@pengutronix.de To unsubscribe, send a mail with subject "unsubscribe" to ptxdist-request@pengutronix.de