Merge pull request #4 from jmarinho/master

Add FW image acceptance details.

source/chapter1-about.rst

@@ -121,15 +121,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
 interpreted as described in :rfc:`2119`.
 
-Cross References
-================
-This document cross-references sources that are listed in the References
-section by using the section sign §.
-
-Examples:
-
-UEFI § 6.1 - Reference to the UEFI specification [UEFI]_ section 6.1
-
 Terms and abbreviations
 =======================
 

source/chapter2-uefi.rst

@@ -47,7 +47,7 @@ rely on information provided by early platform bootstages [FWU]_.
 
 The acceptance status of each FW image is provisionally displayed in the LastAttemptedStatus field [#provisional]_ in the ESRT image entry.
 A value of 0x3fff implies that the image has not been accepted. The OS must
-explicitly accept the image by installing an acceptance capsule as described in `OS directed capsule acceptance`_.
+explicitly accept the image by installing an acceptance capsule as described in `OS directed FW image acceptance`_.
 
 .. [#provisional] Presenting the image acceptance status in the LastAttemptedStatus field is a provisional arrangement. A more permanet solution is under discussion.
 
@@ -74,14 +74,65 @@ When UEFI receives the capsule above, UEFI will change the FWU metadata active_i
 #. Set the active_index field in the FWU Metadata [FWU]_ if the flash store is owned by the Normal World.
 #. Restore EFI variables to their previous state, if changed during the firmware upgrade.
 
-OS directed capsule acceptance
-------------------------------
+.. _OS directed FW image acceptance:
+OS directed FW image acceptance
+-------------------------------
+
+OS declaration of future capsule acceptance responsibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The OS can inform the UEFI implementation of all the FW images that the OS intends to explicitly accept.
 
-.. OS directed capsule acceptance:
+The OS can set the EFI_CAPSULE_HEADER.flags[15] to 1 indicating that it will explicitly accept all the FW images contained in this capsule.
+The OS must be able to accept all images that it registers to accept. Any other images should be implicitly accepted by the UEFI implementation.
 
-The OS must accept the images, which have an acceptance pending, by using the following hollow capsule:
+FW image acceptance
+^^^^^^^^^^^^^^^^^^^
+
+The OS must accept each image, that has an acceptance pending, by using a capsule composed of an EFI_CAPSULE_HEADER concatenated with the image UUID:
 
 - CapsuleGuid 0c996046-bcc0-4d04-85ec-e1fcedf1c6f8
-- HeaderSize = sizeof(EFI_CAPSULE_HEADER)
+- HeaderSize = sizeof(EFI_CAPSULE_HEADER) + sizeof(EFI_GUID)
 - Flags = 0
 - CapsuleImageSize = sizeof(EFI_CAPSULE_HEADER)
+- image_uuid
+
+
+Update permission verification
+------------------------------
+
+The FW management guidelines in [NIST_800_193]_ spacify that the system should check:
+
+#. FW image authenticity.
+#. FW update procedure authorization.
+
+The FW image authenticity should be implemented by authenticating the different FW images.
+The FW update authorization should be implemented by verifying that the capsule or its components were assembled
+by the platform owner.
+
+Capsule authorization
+^^^^^^^^^^^^^^^^^^^^^
+
+The OS can expose the UpdateCapsule interface to any non-priveliged system user.
+The FW updates initiator or the FW update package creator should 
+be an authorized user [NIST_800_193]_.
+
+The capsule or the FW images contained in the capsule should be signed by a platform owner key.
+The UEFI implementation should authenticate the capsule or
+the different fw images included in the capsule using the platform owner key.
+
+The capsule or FW image components are signed by the platform owner in a platform specific way.
+
+The platform owner public key is kept in an platform specific NV region.
+
+FW image authentication
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Each FW image should be signed by the FW vendor. The mechanism for FW image vendor public
+key to be provisioned is outside the scope of this document.
+
+The FW vendor signature should be placed before the FW image as is described in the UEFI FMP definition
+(§ 23.1 [UEFI]_).
+
+The FW images should be authenticated before being written to the FW store or before being
+allowed to execute on the platform.

source/references.rst

@@ -23,3 +23,7 @@ References
 .. [PSBG] `Platform Security Boot Guide
    <https://developer.arm.com/documentation/den0072/0101>`_,
    July 2020, `Arm Limited <http://arm.com>`_
+
+.. [NIST_800_193] `Platform Firmware Resiliency Guidelines
+   <https://csrc.nist.gov/publications/detail/sp/800-193/final>`_,
+   May 2018, NIST