diff mbox series

doc/signed_images.rst: Update instructions for CMS use-case

Message ID 20250320210512.1621778-1-emil.j.granberg@gmail.com
State Accepted
Headers show
Series doc/signed_images.rst: Update instructions for CMS use-case | expand

Commit Message

Emil Granberg March 20, 2025, 9:05 p.m. UTC
Changes added in this commit:
- Updated the CMS certificate generation command to include cert purpose. (Also replaced deprecated parameter -nodes).
- Added note about CONFIG_SIGALG_CMS being required for CMS. (Otherwise the .cert.pem file is interpreted as an RSA public key. when passed with -k to swupdate).

Signed-off-by: Emil Granberg <emil.j.granberg@gmail.com>
---
 doc/source/signed_images.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

Comments

Emil Granberg May 5, 2025, 12:10 p.m. UTC | #1
I pushed this patch a while back but haven’t heard anything back yet. I ran
into some issues when setting up swupdate and I figured I could update the
documentation. If the patch isn’t needed that is also fine, just thought
I’d share it.

/Emil

On Thu, 20 Mar 2025 at 22:05, Emil Granberg <emil.j.granberg@gmail.com>
wrote:

> Changes added in this commit:
> - Updated the CMS certificate generation command to include cert purpose.
> (Also replaced deprecated parameter -nodes).
> - Added note about CONFIG_SIGALG_CMS being required for CMS. (Otherwise
> the .cert.pem file is interpreted as an RSA public key. when passed with -k
> to swupdate).
>
> Signed-off-by: Emil Granberg <emil.j.granberg@gmail.com>
> ---
>  doc/source/signed_images.rst | 16 +++++++++++-----
>  1 file changed, 11 insertions(+), 5 deletions(-)
>
> diff --git a/doc/source/signed_images.rst b/doc/source/signed_images.rst
> index e6a9fd62..9cccbbc0 100644
> --- a/doc/source/signed_images.rst
> +++ b/doc/source/signed_images.rst
> @@ -124,21 +124,24 @@ Generating self-signed certificates
>
>  ::
>
> -        openssl req -x509 -newkey rsa:4096 -nodes -keyout mycert.key.pem \
> -            -out mycert.cert.pem -subj "/O=SWUpdate /CN=target"
> -
> +        openssl req -x509 -newkey rsa:4096 -noenc -keyout mycert.key.pem \
> +            -out mycert.cert.pem -subj "/O=SWUpdate/CN=target" \
> +            -addext extendedKeyUsage=1.3.6.1.5.5.7.3.4 -addext
> keyUsage=digitalSignature
>
>  Check the documentation for more information about parameters. The
> "mycert.key.pem" contains
>  the private key and it is used for signing. It is *not* delivered on the
> target.
>
>  The target must have "mycert.cert.pem" installed - this is used by
> SWUpdate for verification.
>
> +.. note::
> +   The extendedKeyUsage value of "1.3.6.1.5.5.7.3.4" refers to
> "emailProtection". For "codeSigning"
> +   use "1.3.6.1.5.5.7.3.3".
>
>  Using PKI issued certificates
>  .............................
>
>  It is also possible to use PKI issued code signing certificates. However,
> -SWUpdate uses OpenSSL library for handling CMS signatures and the library
> +SWUpdate uses OpenSSL library for handling CMS signatures and by default
> the library
>  requires the following attributes to be set on the signing certificate:
>
>  ::
> @@ -146,6 +149,9 @@ requires the following attributes to be set on the
> signing certificate:
>          keyUsage=digitalSignature
>          extendedKeyUsage=emailProtection
>
> +It is possible to change the default extendedKeyUsage value by setting
> the cert-purpose parameter
> +in swupdate.cfg.
> +
>  It is also possible to completely disable signing certificate key usage
>  checking if this requirement cannot be satisfied. This is controlled by
>  `CONFIG_CMS_IGNORE_CERTIFICATE_PURPOSE` configuration option.
> @@ -283,7 +289,7 @@ If activated, SWUpdate will always check the compound
> image. For security reason
>  it is not possible to disable the check at runtime.
>
>  For RSA and CMS signing, the -k parameter (public key file) is mandatory
> and the program stops
> -if the public key is not passed.
> +if the public key is not passed. For CMS signing, CONFIG_SIGALG_CMS needs
> to be enabled.
>
>  For GPG signing, CONFIG_SIGALG_GPG needs to be enabled. The GPG key will
>  need to be imported to the device's GnuPG home directory. To do this, the
> --
> 2.43.0
>
>
Stefano Babic May 5, 2025, 12:35 p.m. UTC | #2
Hi Emil,

On 5/5/25 14:10, Emil Granberg wrote:
> I pushed this patch a while back but haven’t heard anything back yet. I 
> ran into some issues when setting up swupdate and I figured I could 
> update the documentation.
 > If the patch isn’t needed that is also fine, > just thought I’d share it.

Well, I had already merged your patch a while ago, please check on 
-master...

Best regards,
Stefano Babic

> 
> /Emil
> 
> On Thu, 20 Mar 2025 at 22:05, Emil Granberg <emil.j.granberg@gmail.com 
> <mailto:emil.j.granberg@gmail.com>> wrote:
> 
>     Changes added in this commit:
>     - Updated the CMS certificate generation command to include cert
>     purpose. (Also replaced deprecated parameter -nodes).
>     - Added note about CONFIG_SIGALG_CMS being required for CMS.
>     (Otherwise the .cert.pem file is interpreted as an RSA public key.
>     when passed with -k to swupdate).
> 
>     Signed-off-by: Emil Granberg <emil.j.granberg@gmail.com
>     <mailto:emil.j.granberg@gmail.com>>
>     ---
>       doc/source/signed_images.rst | 16 +++++++++++-----
>       1 file changed, 11 insertions(+), 5 deletions(-)
> 
>     diff --git a/doc/source/signed_images.rst b/doc/source/signed_images.rst
>     index e6a9fd62..9cccbbc0 100644
>     --- a/doc/source/signed_images.rst
>     +++ b/doc/source/signed_images.rst
>     @@ -124,21 +124,24 @@ Generating self-signed certificates
> 
>       ::
> 
>     -        openssl req -x509 -newkey rsa:4096 -nodes -keyout
>     mycert.key.pem \
>     -            -out mycert.cert.pem -subj "/O=SWUpdate /CN=target"
>     -
>     +        openssl req -x509 -newkey rsa:4096 -noenc -keyout
>     mycert.key.pem \
>     +            -out mycert.cert.pem -subj "/O=SWUpdate/CN=target" \
>     +            -addext extendedKeyUsage=1.3.6.1.5.5.7.3.4 -addext
>     keyUsage=digitalSignature
> 
>       Check the documentation for more information about parameters. The
>     "mycert.key.pem" contains
>       the private key and it is used for signing. It is *not* delivered
>     on the target.
> 
>       The target must have "mycert.cert.pem" installed - this is used by
>     SWUpdate for verification.
> 
>     +.. note::
>     +   The extendedKeyUsage value of "1.3.6.1.5.5.7.3.4" refers to
>     "emailProtection". For "codeSigning"
>     +   use "1.3.6.1.5.5.7.3.3".
> 
>       Using PKI issued certificates
>       .............................
> 
>       It is also possible to use PKI issued code signing certificates.
>     However,
>     -SWUpdate uses OpenSSL library for handling CMS signatures and the
>     library
>     +SWUpdate uses OpenSSL library for handling CMS signatures and by
>     default the library
>       requires the following attributes to be set on the signing
>     certificate:
> 
>       ::
>     @@ -146,6 +149,9 @@ requires the following attributes to be set on
>     the signing certificate:
>               keyUsage=digitalSignature
>               extendedKeyUsage=emailProtection
> 
>     +It is possible to change the default extendedKeyUsage value by
>     setting the cert-purpose parameter
>     +in swupdate.cfg.
>     +
>       It is also possible to completely disable signing certificate key
>     usage
>       checking if this requirement cannot be satisfied. This is
>     controlled by
>       `CONFIG_CMS_IGNORE_CERTIFICATE_PURPOSE` configuration option.
>     @@ -283,7 +289,7 @@ If activated, SWUpdate will always check the
>     compound image. For security reason
>       it is not possible to disable the check at runtime.
> 
>       For RSA and CMS signing, the -k parameter (public key file) is
>     mandatory and the program stops
>     -if the public key is not passed.
>     +if the public key is not passed. For CMS signing, CONFIG_SIGALG_CMS
>     needs to be enabled.
> 
>       For GPG signing, CONFIG_SIGALG_GPG needs to be enabled. The GPG
>     key will
>       need to be imported to the device's GnuPG home directory. To do
>     this, the
>     -- 
>     2.43.0
> 
> -- 
> You received this message because you are subscribed to the Google 
> Groups "swupdate" group.
> To unsubscribe from this group and stop receiving emails from it, send 
> an email to swupdate+unsubscribe@googlegroups.com 
> <mailto:swupdate+unsubscribe@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/ 
> swupdate/CAG2JkNG%3Dwt_s4OOMP9OPsoDn3E_QU4- 
> y75vLiLW%2By3PvCFnXnw%40mail.gmail.com <https://groups.google.com/d/ 
> msgid/swupdate/CAG2JkNG%3Dwt_s4OOMP9OPsoDn3E_QU4- 
> y75vLiLW%2By3PvCFnXnw%40mail.gmail.com?utm_medium=email&utm_source=footer>.
diff mbox series

Patch

diff --git a/doc/source/signed_images.rst b/doc/source/signed_images.rst
index e6a9fd62..9cccbbc0 100644
--- a/doc/source/signed_images.rst
+++ b/doc/source/signed_images.rst
@@ -124,21 +124,24 @@  Generating self-signed certificates
 
 ::
 
-        openssl req -x509 -newkey rsa:4096 -nodes -keyout mycert.key.pem \
-            -out mycert.cert.pem -subj "/O=SWUpdate /CN=target"
-
+        openssl req -x509 -newkey rsa:4096 -noenc -keyout mycert.key.pem \
+            -out mycert.cert.pem -subj "/O=SWUpdate/CN=target" \
+            -addext extendedKeyUsage=1.3.6.1.5.5.7.3.4 -addext keyUsage=digitalSignature
 
 Check the documentation for more information about parameters. The "mycert.key.pem" contains
 the private key and it is used for signing. It is *not* delivered on the target.
 
 The target must have "mycert.cert.pem" installed - this is used by SWUpdate for verification.
 
+.. note::
+   The extendedKeyUsage value of "1.3.6.1.5.5.7.3.4" refers to "emailProtection". For "codeSigning"
+   use "1.3.6.1.5.5.7.3.3".
 
 Using PKI issued certificates
 .............................
 
 It is also possible to use PKI issued code signing certificates. However,
-SWUpdate uses OpenSSL library for handling CMS signatures and the library
+SWUpdate uses OpenSSL library for handling CMS signatures and by default the library
 requires the following attributes to be set on the signing certificate:
 
 ::
@@ -146,6 +149,9 @@  requires the following attributes to be set on the signing certificate:
         keyUsage=digitalSignature
         extendedKeyUsage=emailProtection
 
+It is possible to change the default extendedKeyUsage value by setting the cert-purpose parameter
+in swupdate.cfg.
+
 It is also possible to completely disable signing certificate key usage
 checking if this requirement cannot be satisfied. This is controlled by
 `CONFIG_CMS_IGNORE_CERTIFICATE_PURPOSE` configuration option.
@@ -283,7 +289,7 @@  If activated, SWUpdate will always check the compound image. For security reason
 it is not possible to disable the check at runtime.
 
 For RSA and CMS signing, the -k parameter (public key file) is mandatory and the program stops 
-if the public key is not passed.
+if the public key is not passed. For CMS signing, CONFIG_SIGALG_CMS needs to be enabled.
 
 For GPG signing, CONFIG_SIGALG_GPG needs to be enabled. The GPG key will
 need to be imported to the device's GnuPG home directory. To do this, the