diff mbox series

[5/5] doc: uefi: clarify capsule concept

Message ID 20230616113426.13976-6-stefan.herbrechtsmeier-oss@weidmueller.com
State Changes Requested, archived
Delegated to: Heinrich Schuchardt
Headers show
Series Extend mkeficapsule tool to pack multiple payloads | expand

Commit Message

Stefan Herbrechtsmeier June 16, 2023, 11:34 a.m. UTC 
From: Malte Schmidt <malte.schmidt@weidmueller.com>

There seems to be some misused or inaccurate namings regarding the capsule
concept. Set the naming straight and add a table showing the naming
conventions. This table is based on the images found in chapter 23 of the
UEFI 2.10 specifications [1]. The table should help to build a common
understanding between the authors and readers of the documentation.

[1] https://uefi.org/specs/UEFI/2.10/index.html

Signed-off-by: Malte Schmidt <malte.schmidt@weidmueller.com>

Signed-off-by: Stefan Herbrechtsmeier <stefan.herbrechtsmeier@weidmueller.com>
---

 doc/develop/uefi/uefi.rst | 42 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

Comments

Heinrich Schuchardt June 16, 2023, 5:50 p.m. UTC | #1 
On 6/16/23 13:34, Stefan Herbrechtsmeier wrote:
> From: Malte Schmidt <malte.schmidt@weidmueller.com>
>
> There seems to be some misused or inaccurate namings regarding the capsule
> concept. Set the naming straight and add a table showing the naming
> conventions. This table is based on the images found in chapter 23 of the
> UEFI 2.10 specifications [1]. The table should help to build a common
> understanding between the authors and readers of the documentation.
>
> [1] https://uefi.org/specs/UEFI/2.10/index.html
>
> Signed-off-by: Malte Schmidt <malte.schmidt@weidmueller.com>
>
> Signed-off-by: Stefan Herbrechtsmeier <stefan.herbrechtsmeier@weidmueller.com>
> ---
>
>   doc/develop/uefi/uefi.rst | 42 ++++++++++++++++++++++++++++++++++++---
>   1 file changed, 39 insertions(+), 3 deletions(-)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index b513934d31..56188c5b10 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -300,6 +300,42 @@ not present are ignored when determining the active boot option.
>   Please note that capsules will be applied in the alphabetic order of
>   capsule file names.
>
> +Structure of a capsule file
> +***************************
> +
> +The strucutre of a firmware management capsule as defined in [1] is shown

%s/strucutre/structure/

Best regards

Heinrich

> +below. The tools/mkeficapsule program supports creating firmware management
> +capsules with multiple payloads and optionally with firmware image
> +authentication.
> +
> +.. code-block:: text
> +
> +    +-------------------------------------------------------------------------+
> +    | EFI_CAPSULE_HEADER                                                      |
> +    +--------------+----------------------------------------------------------+
> +    | Capsule Body | EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER                   |
> +    |              +----------------------------------------------------------+
> +    |              | Optional Driver 1                                        |
> +    |              +----------------------------------------------------------+
> +    |              | Optional Driver 2                                        |
> +    |              +----------------------------------------------------------+
> +    |              | ...                                                      |
> +    |              +-----------+----------------------------------------------+
> +    |              | Payload 1 | EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER |
> +    |              |           +----------------------------------------------+
> +    |              |           | Firmware Image Authentication (optional)     |
> +    |              |           +----------------------------------------------+
> +    |              |           | Dependency Expression (optional)             |
> +    |              |           +----------------------------------------------+
> +    |              |           | Firmware Image                               |
> +    |              +-----------+----------------------------------------------+
> +    |              | Payload 2                                                |
> +    |              +----------------------------------------------------------+
> +    |              | ...                                                      |
> +    |              +----------------------------------------------------------+
> +    |              | Payload n                                                |
> +    +--------------+----------------------------------------------------------+
> +
>   Creating a capsule file
>   ***********************
>
> @@ -482,9 +518,9 @@ following command can be issued
>   Enabling Capsule Authentication
>   *******************************
>
> -The UEFI specification defines a way of authenticating the capsule to
> -be updated by verifying the capsule signature. The capsule signature
> -is computed and prepended to the capsule payload at the time of
> +The UEFI specification defines a way of authenticating the capsule payload
> +to be updated by verifying the signature of each capsule payload. The payload
> +signature is computed and prepended to the capsule payload at the time of
>   capsule generation. This signature is then verified by using the
>   public key stored as part of the X509 certificate. This certificate is
>   in the form of an efi signature list (esl) file, which is embedded in
diff mbox series

Patch

diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index b513934d31..56188c5b10 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -300,6 +300,42 @@  not present are ignored when determining the active boot option.
 Please note that capsules will be applied in the alphabetic order of
 capsule file names.
 
+Structure of a capsule file
+***************************
+
+The strucutre of a firmware management capsule as defined in [1] is shown
+below. The tools/mkeficapsule program supports creating firmware management
+capsules with multiple payloads and optionally with firmware image
+authentication.
+
+.. code-block:: text
+
+    +-------------------------------------------------------------------------+
+    | EFI_CAPSULE_HEADER                                                      |
+    +--------------+----------------------------------------------------------+
+    | Capsule Body | EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER                   |
+    |              +----------------------------------------------------------+
+    |              | Optional Driver 1                                        |
+    |              +----------------------------------------------------------+
+    |              | Optional Driver 2                                        |
+    |              +----------------------------------------------------------+
+    |              | ...                                                      |
+    |              +-----------+----------------------------------------------+
+    |              | Payload 1 | EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER |
+    |              |           +----------------------------------------------+
+    |              |           | Firmware Image Authentication (optional)     |
+    |              |           +----------------------------------------------+
+    |              |           | Dependency Expression (optional)             |
+    |              |           +----------------------------------------------+
+    |              |           | Firmware Image                               |
+    |              +-----------+----------------------------------------------+
+    |              | Payload 2                                                |
+    |              +----------------------------------------------------------+
+    |              | ...                                                      |
+    |              +----------------------------------------------------------+
+    |              | Payload n                                                |
+    +--------------+----------------------------------------------------------+
+
 Creating a capsule file
 ***********************
 
@@ -482,9 +518,9 @@  following command can be issued
 Enabling Capsule Authentication
 *******************************
 
-The UEFI specification defines a way of authenticating the capsule to
-be updated by verifying the capsule signature. The capsule signature
-is computed and prepended to the capsule payload at the time of
+The UEFI specification defines a way of authenticating the capsule payload
+to be updated by verifying the signature of each capsule payload. The payload
+signature is computed and prepended to the capsule payload at the time of
 capsule generation. This signature is then verified by using the
 public key stored as part of the X509 certificate. This certificate is
 in the form of an efi signature list (esl) file, which is embedded in