---?image=assets/images/gitpitch-audience.jpg
@title[Platform Build Lab]
tianocore.org Note: PITCHME.md for UEFI / EDK II Training Capsule Update Pres
Copyright (c) 2018, Intel Corporation. All rights reserved.
Redistribution and use in source (original document form) and 'compiled' forms (converted to PDF, epub, HTML and other formats) with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code (original document form) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
-
Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@title[Lesson Objective]
@fa[certificate gp-bullet-green] What is Capsule Update
@fa[certificate gp-bullet-cyan] Why is Capsule Update needed
@fa[certificate gp-bullet-yellow] How to enable Capsule Update in Edk II platforms
---?image=assets/images/binary-strings-black2.jpg
@title[UEFI Aware OS Requirements Section]
@title[What is Capsule Update Video]
Note:
Capsule Update is a MORE secure way to update the firmware using a firmware image where the capsule is a file that contains a firmware update image.
A security benefit is that the capsule update method only works if the existing image on the target system has the same
signature as used with to build the original Firmware image currently on the target system.
When the Capsule update method is enabled, The EDK II Build will generate a firmware image in for form of a capsule or file. The file will have a .CAP extension.
The EDK II Build process will also create a UEFI Shell application called “CapsuleAPP.efi” that will use the capsule file.
When the Capsule update method is enabled, the verification method can also be selected for how a firmware update image is verified, or authenticated, before it is used. The verifications methods are NONE, Test or user generated.
Image authentication is typically required for shipping products to make sure only valid firmware update images are applied to a specific product.
When the UEFI Shell application, CapsuleAPP, is invoked with a .CAP file image, the target system will reboot twice. The first time to authenticate the firmware update image and update the FLASH device. The second time to boot using the updated FLASH device.
---?image=/assets/images/slides/Slide5.JPG
@title[Why Capsule Update Needed]
Why is Capsule Update Needed?
Establish a Root-of-Trust at the low-level platform initializationNational Institute of Standards and Technology (NIST) provides guidelines on BIOS update, [800-147]
- BIOS Update Authentication
- Secure Local Update Method
- Integrity Protection
- Non-Bypassabilitiy
NIST: SP 800-147 .pdf
Note:
Firmware is responsible for low-level platform initialization and hand-off to the operating system.
This means firmware establishes root-of-trust for the platform. Signed capsules help assure that the correct update is being applied to the platform.
Using signed images with UEFI Capsule allows an OS-agnostic process to provide verified firmware updates, utilizing root-of-trust established by the firmware.
This scenario assumes the factory-provisioned firmware and subsequent updates are signed with the same public/private keypair.
+++?image=/assets/images/slides/Slide6_1.JPG
@title[Why Capsule Update Needed]
Why is Capsule Update Needed?
Establish a Root-of-Trust at the low-level platform initializationNational Institute of Standards and Technology (NIST) provides guidelines on BIOS update, [800-147]
- BIOS Update Authentication
- Secure Local Update Method
- Integrity Protection
- Non-Bypassabilitiy
Does not describe implementation – the
NIST: SP 800-147 .pdf
Note:
Firmware is responsible for low-level platform initialization and hand-off to the operating system.
This means firmware establishes root-of-trust for the platform. Signed capsules help assure that the correct update is being applied to the platform.
Using signed images with UEFI Capsule allows an OS-agnostic process to provide verified firmware updates, utilizing root-of-trust established by the firmware.
This scenario assumes the factory-provisioned firmware and subsequent updates are signed with the same public/private keypair.
---?image=/assets/images/slides/Slide8.JPG @title[Solving Firmware Update]
Solving Firmware Update
- Reliable update story
- Fault tolerant
- Scalable & repeatable
- How can UEFI Help?
- Capsule model for binary delivery
- Bus / Device Enumeration
- Managing updates via:
EFI System Resoure Table, Firmware Management Protocol (FMP) and
Capsule Signing
Note:
- UEFI open platforms_Vincent.ppt slide 24 - CanSecWest 2015 - Refrences [6]: https://firmware.intel.com/blog/security-technologies-and-minnowboard-max?page=1
---?image=assets/images/binary-strings-black2.jpg
@title[How does the Capsule Update work? Section]
@title[UEFI Spec defines Capsule Services ]
UEFI Spec defines Capsule Services to meet NIST Requirements
- EFI_FIRMWARE_MANAGEMENT_PROTOCOL, (FMP) capsule format |
- EFI System Resource Table (ESRT) to support system firmware and device firmware update |
- An OS agnostic UEFI service
UpdateCapsule()may be called to pass the capsule image from the OS to the firmware. Based upon the capsule flags, the firmware may process the capsule image immediately, or the firmware may reset the system and process the capsule image on the next boot |
Note:
Same as slide
---?image=/assets/images/slides/Slide12.JPG @title[UEFI Capsule Update – (FMP)]
UEFI Capsule Update – Firmware Management Protocol (FMP)
Note:
- FMP capsule image format
- Update FMP drivers
- FMP payloads
- binary update image and optional vendor code
- The platform may consume a FMP protocol to update the firmware image
The FMP capsule image format is shown in This slide. It contains the update FMP drivers and the FMP payloads. The FMP payload contains the binary update image and optional vendor code. The platform may consume a FMP protocol to update the firmware image.
The UEFI specification [UEFI] defines UEFI capsule services, EFI_FIRMWARE_MANAGEMENT_PROTOCOL, FMP capsule format and EFI System Resource Table (ESRT) to support system firmware and device firmware update. The platform may consume a system FMP and a device FMP protocol to get the firmware image information and report the ESRT to a UEFI OS. An OS agent may call the UEFI service UpdateCapsule() to pass the capsule image from the OS to the firmware. Based upon the capsule flags, the firmware may process the capsule image immediately, or the firmware may reset the system and process the capsule image on the next boot.
---?image=/assets/images/slides/Slide14.JPG
@title[Capsule Update - flow ]
Note:
one possible way is that the operating system sends a firmware image to the system and lets the system update the flash device before the flash device is locked in next boot. This slide. This firmware image is called a “capsule”. The UEFI specification defines a set of capsule services to let operating system pass the information to the firmware. The UEFI specification also defines the capsule image format for the EFI_FIRMWARE_MANAGEMENT_PROTOCOL (FMP).
EDKII provides the sample drivers to performance the signed system firmware update via the capsule interface. It follows the NIST standard, Microsoft design and the UEFI specification.
+++?image=/assets/images/slides/Slide15.JPG
@title[Capsule Update - flow 02]
Note:
one possible way is that the operating system sends a firmware image to the system and lets the system update the flash device before the flash device is locked in next boot. This slide. This firmware image is called a “capsule”. The UEFI specification defines a set of capsule services to let operating system pass the information to the firmware. The UEFI specification also defines the capsule image format for the EFI_FIRMWARE_MANAGEMENT_PROTOCOL (FMP).
EDKII provides the sample drivers to performance the signed system firmware update via the capsule interface. It follows the NIST standard, Microsoft design and the UEFI specification.
+++?image=/assets/images/slides/Slide16.JPG
@title[Capsule Update - flow 03]
Note:
one possible way is that the operating system sends a firmware image to the system and lets the system update the flash device before the flash device is locked in next boot. This slide. This firmware image is called a “capsule”. The UEFI specification defines a set of capsule services to let operating system pass the information to the firmware. The UEFI specification also defines the capsule image format for the EFI_FIRMWARE_MANAGEMENT_PROTOCOL (FMP).
EDKII provides the sample drivers to performance the signed system firmware update via the capsule interface. It follows the NIST standard, Microsoft design and the UEFI specification.
---?image=/assets/images/slides/Slide18.JPG @title[UEFI Firmware Secure “Capsule” Update]
UEFI Firmware Secure “Capsule” Update
Note:
Capsule update is a runtime service used to update UEFI FW
- Update is initiated by update application/OS runtime
- Update application stores update “capsule” in DRAM or HDD on ESP (e.g. \EFI\CapsuleUpdate)
- Upon reboot or S3 resume, FW finds and parses update capsule
- After FW verifies digital signature of the capsule, FW writes new BIOS FV(s) to SPI flash memory
---?image=/assets/images/slides/Slide20.JPG @title[Delivering Update “Capsules” in OS]
Delivering Update “Capsules” in OS
Note:
Source: https://firmware.intel.com/blog/security-technologies-and-minnowboard-max?page=1 UEFI open platforms_Vincent.ppt slide 24 - CanSecWest 2015 - Refrences [6]: reference # [6] Slide 25 of PPT
- UEFI supports Capsule format
- Tools for capsule generation
- Core logic for capsule handling
- Extensible Capsule format
- Self-contained
- Discrete updates
- Composite updates
- Firmware Management Protocol allows
- Reading / updating firmware
- Integrity checks
---?image=/assets/images/slides/Slide22.JPG @title[Firmware Update Rollback Protection]
Firmware Update Rollback Protection
Note:
Source: https://firmware.intel.com/blog/security-technologies-and-minnowboard-max?page=1 UEFI open platforms_Vincent.ppt slide 24 - CanSecWest 2015 - Refrences [6]: reference # [6] Slide 26 of PPT
- Each version fixes some issues with the previous. Since none are known to have security flaws, each new version allows updates to all older versions.
- In V4, one of the issues fixed in V3 is realized to be a security fix. V4 will not allow updates to earlier versions, even V3 since it allows update to V2.
- Version 5 can now accept only versions 5 and 4.
---?image=assets/images/binary-strings-black2.jpg
@title[How to Enable Capsule Update Section]
How to Enable Capsule Update on a EDK II Platform?
---?image=/assets/images/slides/Slide25.JPG
@title[UEFI Capsule Implementation in EDK II]
UEFI Capsule Implementation in EDK II
SignedCapsulePkg Uses OpenSSLto sign and authenticate firmware update capsules and firmware recovery images
Note:
- Test signing key
- used for firmware development and debug
- Production signing key
- used by OEM to create and manage their own
- OpenSLL utilities can be used to create key
+++?image=/assets/images/slides/Slide26.JPG
@title[UEFI Capsule Implementation in EDK II]
UEFI Capsule Implementation in EDK II
SignedCapsulePkg Uses OpenSSLto sign and authenticate firmware update capsules and firmware recovery images
Note:
- Test signing key
- used for firmware development and debug
- Production signing key
- used by OEM to create and manage their own
- OpenSLL utilities can be used to create key
@title[Enable Capsule Based System Firmware Update]
Enable Capsule Based System Firmware Update
The following wiki link pages provide details on how to add the system firmware update using Signed UEFI Capsules
- Implement Platform Components for UEFI Capsule : link - Add CAPSULE_ENABLE feature to Platform DSC/FDF Files : link - Verify CAPSULE_ENABLE feature using Test Signing Keys : link - Change System Firmware Update Version : link - Change ESRT System Firmware Update GUID : link - How to Generate Signing Keys using OpenSSL Command Line Utilities : link - Verify CAPSULE_ENABLE feature using Generated Signing Keys : link
Note:
Same as slide
---?image=/assets/images/slides/Slide29.JPG
@title[Implement Platform Components for UEFI Capsule]
Implement Platform Components for UEFI Capsule
Example from Minnowboard Max/Turbot platform: github link
Note:
In order for a signed capsule to update the non-volatile storage device that that contains the system firmware contents that may be updated, an instance of the PlatformFlashAccessLib must be implemented. This library class provides a single API to update a portion of the non-volatile storage device.
The System Firmware Descriptor information is implemented in the file SystemFirmwareDescriptor.aslc. The version and string information must be updated for the system firmware update requirements. The IMAGE_TYPE_ID_GUID define must be set to a new GUID value(using C structure syntax) for the platform. This GUID value must be one of the GUID values the platform supports for Capsule Base System Firmware Updates. The PCD called gEfiMdeModulePkgTokenSpaceGuid.PcdSystemFmpCapsuleImageTypeIdGuid is set to an array of one or more of IMAGE_TYPE_ID_GUID values (using byte array syntax) in the Platform DSC file described
his a System Firmware Update Configuration INI file provides the inventory of components in a capsule that are used by the system firmware's Firmware Management Protocol to update one or more components in the system firmware's non-volatile storage device using the PlatformFlashAccessLib instance implemented in the step above. The INI file is ASCII text. The first section is [Head]. The value of NumHeadUpdate must be set to the number of components in the inventory. There must be an UpdateX statement assigned to a unique name for each component in the inventory.
+++?image=/assets/images/slides/Slide30.JPG
@title[Implement Platform Components for UEFI Capsule 02]
Implement Platform Components for UEFI Capsule
Example from Minnowboard Max/Turbot platform: github link
Note:
In order for a signed capsule to update the non-volatile storage device that that contains the system firmware contents that may be updated, an instance of the PlatformFlashAccessLib must be implemented. This library class provides a single API to update a portion of the non-volatile storage device.
The System Firmware Descriptor information is implemented in the file SystemFirmwareDescriptor.aslc. The version and string information must be updated for the system firmware update requirements. The IMAGE_TYPE_ID_GUID define must be set to a new GUID value(using C structure syntax) for the platform. This GUID value must be one of the GUID values the platform supports for Capsule Base System Firmware Updates. The PCD called gEfiMdeModulePkgTokenSpaceGuid.PcdSystemFmpCapsuleImageTypeIdGuid is set to an array of one or more of IMAGE_TYPE_ID_GUID values (using byte array syntax) in the Platform DSC file described
his a System Firmware Update Configuration INI file provides the inventory of components in a capsule that are used by the system firmware's Firmware Management Protocol to update one or more components in the system firmware's non-volatile storage device using the PlatformFlashAccessLib instance implemented in the step above. The INI file is ASCII text. The first section is [Head]. The value of NumHeadUpdate must be set to the number of components in the inventory. There must be an UpdateX statement assigned to a unique name for each component in the inventory.
+++?image=/assets/images/slides/Slide31.JPG
@title[Implement Platform Components for UEFI Capsule 03]
Implement Platform Components for UEFI Capsule
Example from Minnowboard Max/Turbot platform: github link
Note:
In order for a signed capsule to update the non-volatile storage device that that contains the system firmware contents that may be updated, an instance of the PlatformFlashAccessLib must be implemented. This library class provides a single API to update a portion of the non-volatile storage device.
The System Firmware Descriptor information is implemented in the file SystemFirmwareDescriptor.aslc. The version and string information must be updated for the system firmware update requirements. The IMAGE_TYPE_ID_GUID define must be set to a new GUID value(using C structure syntax) for the platform. This GUID value must be one of the GUID values the platform supports for Capsule Base System Firmware Updates. The PCD called gEfiMdeModulePkgTokenSpaceGuid.PcdSystemFmpCapsuleImageTypeIdGuid is set to an array of one or more of IMAGE_TYPE_ID_GUID values (using byte array syntax) in the Platform DSC file described
his a System Firmware Update Configuration INI file provides the inventory of components in a capsule that are used by the system firmware's Firmware Management Protocol to update one or more components in the system firmware's non-volatile storage device using the PlatformFlashAccessLib instance implemented in the step above. The INI file is ASCII text. The first section is [Head]. The value of NumHeadUpdate must be set to the number of components in the inventory. There must be an UpdateX statement assigned to a unique name for each component in the inventory.
+++?image=/assets/images/slides/Slide32.JPG
@title[Implement Platform Components for UEFI Capsule 04]
Implement Platform Components for UEFI Capsule
Example from Minnowboard Max/Turbot platform: github link
Note:
In order for a signed capsule to update the non-volatile storage device that that contains the system firmware contents that may be updated, an instance of the PlatformFlashAccessLib must be implemented. This library class provides a single API to update a portion of the non-volatile storage device.
The System Firmware Descriptor information is implemented in the file SystemFirmwareDescriptor.aslc. The version and string information must be updated for the system firmware update requirements. The IMAGE_TYPE_ID_GUID define must be set to a new GUID value(using C structure syntax) for the platform. This GUID value must be one of the GUID values the platform supports for Capsule Base System Firmware Updates. The PCD called gEfiMdeModulePkgTokenSpaceGuid.PcdSystemFmpCapsuleImageTypeIdGuid is set to an array of one or more of IMAGE_TYPE_ID_GUID values (using byte array syntax) in the Platform DSC file described
his a System Firmware Update Configuration INI file provides the inventory of components in a capsule that are used by the system firmware's Firmware Management Protocol to update one or more components in the system firmware's non-volatile storage device using the PlatformFlashAccessLib instance implemented in the step above. The INI file is ASCII text. The first section is [Head]. The value of NumHeadUpdate must be set to the number of components in the inventory. There must be an UpdateX statement assigned to a unique name for each component in the inventory.
---?image=/assets/images/slides/Slide34.JPG @title[Add CAPSULE_ENABLE feature ]
Add `CAPSULE_ENABLE` feature to Platform Files
- Add `-D CAPSULE_ENABLE` to the build command line to enable capsule update features.
- The build process generates a capsule update image (.cap file) along with the UEFI application `CapsuleApp.efi`.
- Copy `.cap` file and `CapsuleApp.efi` to USB thumb drive
- Boot to UEFI Shell and use `CapsuleApp.efi` with `.cap` signed capsule file
- Once the system is rebooted, the signed capsule is authenticated and the firmware is update with the new system firmware version.
Note:
- Add -D CAPSULE_ENABLE to the build command line to enable capsule update features.
- The build process generates a capsule update image (.cap file) along with the UEFI application CapsuleApp.efi.
- These 2 files must be transferred to storage media to in order for a user to boot to UEFI Shell and use CapsuleApp.efi to submit the signed capsule. Once the system is rebooted, the signed capsule is authenticated and the firmware is update with the new system firmware version.
- Platform DSC Sections: - [LibraryClasses] - [Pcds] - [Components] - Platform FDF Sections: - [FV] PEI - [FV] DXE - [FV] Platform - [VmpPayload] - [Capsule] - [Rule]
---?image=/assets/images/slides/Slide36.JPG
@title[Verify CAPSULE_ENABLE Feature ]
Verify `CAPSULE_ENABLE` Feature w/ Test Signing Keys
- Download the OpenSSL library
- Build the Boot Firmware image with `CAPSULE_ENABLE`
- Copy the `CapsuleApp.efi` to USB thumb drive and run on Target system
Note:
- Download the OpenSSL library
- Build the Boot Firmware image with CAPSULE_ENABLE
- Copy the CapsuleApp.efi to USB thumb drive and run on Target system
---?image=/assets/images/slides/Slide38.JPG
@title[Verify Capsule Enable -P ]
Verify `CAPSULE_ENABLE` with `CapsuleApp -P` option
Note:
---?image=/assets/images/slides/Slide39.JPG
@title[Verify Capsule Enable -E ]
Verify `CAPSULE_ENABLE` with `CapsuleApp -E` option
Note:
@title[Summary]
@fa[certificate gp-bullet-green] What is Capsule Update
@fa[certificate gp-bullet-cyan] Why is Capsule Update needed
@fa[certificate gp-bullet-yellow] How to enable Capsule Update in Edk II platforms
---?image=assets/images/gitpitch-audience.jpg
@title[Questions]
---?image=assets/images/gitpitch-audience.jpg
@title[Logo Slide]
@title[Acknowledgements]
/**
Redistribution and use in source (original document form) and 'compiled' forms (converted
to PDF, epub, HTML and other formats) with or without modification, are permitted provided
that the following conditions are met:
Redistributions of source code (original document form) must retain the above copyright
notice, this list of conditions and the following disclaimer as the first lines of this
file unmodified.
Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML
and other formats) must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the
distribution.
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
Copyright (c) 2018, Intel Corporation. All rights reserved.
**/