[PATCH v3] ref-manual: document authentication key variables

[PATCH v3] ref-manual: document authentication key variables

[Usama Arif]

This documents the variables used to create keys for
signing fitImage.

Signed-off-by: Usama Arif <usama.arif@arm.com>
---
 documentation/ref-manual/ref-classes.rst   |  4 +++-
 documentation/ref-manual/ref-variables.rst | 23 ++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst
index 60ce8efd21..b007e34826 100644
--- a/documentation/ref-manual/ref-classes.rst
+++ b/documentation/ref-manual/ref-classes.rst
@@ -1413,7 +1413,9 @@ variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
 :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
 appropriately. The default values used for :term:`FIT_HASH_ALG` and
 :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
-"rsa2048" respectively.
+"rsa2048" respectively. The keys for signing fitImage can be generated using
+the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
+:term:`UBOOT_SIGN_ENABLE` are set to "1".
 
 
 .. _ref-classes-kernel-grub:
diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
index cf37703814..e206871c94 100644
--- a/documentation/ref-manual/ref-variables.rst
+++ b/documentation/ref-manual/ref-variables.rst
@@ -2585,6 +2585,11 @@ system and gives an overview of their function and contents.
       For guidance on how to create your own file permissions settings
       table file, examine the existing ``fs-perms.txt``.
 
+   FIT_GENERATE_KEYS
+      Decides whether to generate the keys for signing fitImage if they
+      don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``.
+      The default value is 0.
+
    FIT_HASH_ALG
       Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
 
@@ -2592,6 +2597,24 @@ system and gives an overview of their function and contents.
       Specifies the signature algorithm used in creating the FIT Image.
       For e.g. rsa2048.
 
+   FIT_SIGN_NUMBITS
+      Size of private key in number of bits used in fitImage. The default
+      value is "2048".
+
+   FIT_KEY_GENRSA_ARGS
+      Arguments to openssl genrsa for generating RSA private key for signing
+      fitImage. The default value is "-F4". i.e. the public exponent 65537 to
+      use.
+
+   FIT_KEY_REQ_ARGS
+      Arguments to openssl req for generating certificate for signing fitImage.
+      The default value is "-batch -new". batch for non interactive mode
+      and new for generating new keys.
+
+   FIT_KEY_SIGN_PKCS
+      Format for public key ceritifcate used in signing fitImage.
+      The default value is "x509".
+
    FONT_EXTRA_RDEPENDS
       When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
       this variable specifies the runtime dependencies for font packages.
-- 
2.17.1

Re: [docs] [PATCH v3] ref-manual: document authentication key variables

[Nicolas Dechesne]

On Wed, Sep 30, 2020 at 5:03 PM Usama Arif <usama.arif@arm.com> wrote:
>
> This documents the variables used to create keys for
> signing fitImage.
>
> Signed-off-by: Usama Arif <usama.arif@arm.com>
> ---
>  documentation/ref-manual/ref-classes.rst   |  4 +++-
>  documentation/ref-manual/ref-variables.rst | 23 ++++++++++++++++++++++
>  2 files changed, 26 insertions(+), 1 deletion(-)
>
> diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst
> index 60ce8efd21..b007e34826 100644
> --- a/documentation/ref-manual/ref-classes.rst
> +++ b/documentation/ref-manual/ref-classes.rst
> @@ -1413,7 +1413,9 @@ variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
>  :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
>  appropriately. The default values used for :term:`FIT_HASH_ALG` and
>  :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
> -"rsa2048" respectively.
> +"rsa2048" respectively. The keys for signing fitImage can be generated using
> +the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
> +:term:`UBOOT_SIGN_ENABLE` are set to "1".
>
>
>  .. _ref-classes-kernel-grub:
> diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
> index cf37703814..e206871c94 100644
> --- a/documentation/ref-manual/ref-variables.rst
> +++ b/documentation/ref-manual/ref-variables.rst
> @@ -2585,6 +2585,11 @@ system and gives an overview of their function and contents.
>        For guidance on how to create your own file permissions settings
>        table file, examine the existing ``fs-perms.txt``.
>
> +   FIT_GENERATE_KEYS
> +      Decides whether to generate the keys for signing fitImage if they
> +      don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``.
> +      The default value is 0.
> +
>     FIT_HASH_ALG
>        Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
>
> @@ -2592,6 +2597,24 @@ system and gives an overview of their function and contents.
>        Specifies the signature algorithm used in creating the FIT Image.
>        For e.g. rsa2048.
>
> +   FIT_SIGN_NUMBITS
> +      Size of private key in number of bits used in fitImage. The default
> +      value is "2048".
> +
> +   FIT_KEY_GENRSA_ARGS
> +      Arguments to openssl genrsa for generating RSA private key for signing
> +      fitImage. The default value is "-F4". i.e. the public exponent 65537 to
> +      use.
> +
> +   FIT_KEY_REQ_ARGS
> +      Arguments to openssl req for generating certificate for signing fitImage.
> +      The default value is "-batch -new". batch for non interactive mode
> +      and new for generating new keys.
> +
> +   FIT_KEY_SIGN_PKCS
> +      Format for public key ceritifcate used in signing fitImage.
> +      The default value is "x509".
> +

We probably should be sorted alphabetically.

>     FONT_EXTRA_RDEPENDS
>        When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
>        this variable specifies the runtime dependencies for font packages.
> --
> 2.17.1
>
>
> 
>

Re: [docs] [PATCH v3] ref-manual: document authentication key variables

[Usama Arif]

On 30/09/2020 20:28, Nicolas Dechesne via lists.yoctoproject.org wrote:
> On Wed, Sep 30, 2020 at 5:03 PM Usama Arif <usama.arif@arm.com> wrote:
>>
>> This documents the variables used to create keys for
>> signing fitImage.
>>
>> Signed-off-by: Usama Arif <usama.arif@arm.com>
>> ---
>>   documentation/ref-manual/ref-classes.rst   |  4 +++-
>>   documentation/ref-manual/ref-variables.rst | 23 ++++++++++++++++++++++
>>   2 files changed, 26 insertions(+), 1 deletion(-)
>>
>> diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst
>> index 60ce8efd21..b007e34826 100644
>> --- a/documentation/ref-manual/ref-classes.rst
>> +++ b/documentation/ref-manual/ref-classes.rst
>> @@ -1413,7 +1413,9 @@ variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
>>   :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
>>   appropriately. The default values used for :term:`FIT_HASH_ALG` and
>>   :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
>> -"rsa2048" respectively.
>> +"rsa2048" respectively. The keys for signing fitImage can be generated using
>> +the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
>> +:term:`UBOOT_SIGN_ENABLE` are set to "1".
>>
>>
>>   .. _ref-classes-kernel-grub:
>> diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
>> index cf37703814..e206871c94 100644
>> --- a/documentation/ref-manual/ref-variables.rst
>> +++ b/documentation/ref-manual/ref-variables.rst
>> @@ -2585,6 +2585,11 @@ system and gives an overview of their function and contents.
>>         For guidance on how to create your own file permissions settings
>>         table file, examine the existing ``fs-perms.txt``.
>>
>> +   FIT_GENERATE_KEYS
>> +      Decides whether to generate the keys for signing fitImage if they
>> +      don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``.
>> +      The default value is 0.
>> +
>>      FIT_HASH_ALG
>>         Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
>>
>> @@ -2592,6 +2597,24 @@ system and gives an overview of their function and contents.
>>         Specifies the signature algorithm used in creating the FIT Image.
>>         For e.g. rsa2048.
>>
>> +   FIT_SIGN_NUMBITS
>> +      Size of private key in number of bits used in fitImage. The default
>> +      value is "2048".
>> +
>> +   FIT_KEY_GENRSA_ARGS
>> +      Arguments to openssl genrsa for generating RSA private key for signing
>> +      fitImage. The default value is "-F4". i.e. the public exponent 65537 to
>> +      use.
>> +
>> +   FIT_KEY_REQ_ARGS
>> +      Arguments to openssl req for generating certificate for signing fitImage.
>> +      The default value is "-batch -new". batch for non interactive mode
>> +      and new for generating new keys.
>> +
>> +   FIT_KEY_SIGN_PKCS
>> +      Format for public key ceritifcate used in signing fitImage.
>> +      The default value is "x509".
>> +
> 
> We probably should be sorted alphabetically.
> 

Thanks, fixed in v4.

Regards,
Usama

>>      FONT_EXTRA_RDEPENDS
>>         When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
>>         this variable specifies the runtime dependencies for font packages.
>> --
>> 2.17.1
>>
>>
>>
>>
>>
>>
>> 
>>