From 0aeddee98ba00e6ba27c45f15447fa5ff74eeb4f Mon Sep 17 00:00:00 2001 From: Bret Barkelew Date: Thu, 8 Jul 2021 21:14:58 -0700 Subject: [PATCH] capsule: Update CapsuleHelper to process integrity file (#254) Update CapsuleHeader to check for the 'fw_integrity_file' capsule option and, if present, set the field in the InfGenerator so that the INF file has the definitions for the integrity file. Co-authored-by: Bret Barkelew --- edk2toolext/capsule/Readme.md | 40 +++++++++++++++++++ edk2toolext/capsule/capsule_helper.py | 19 +++++---- .../tests/capsule/capsule_helper_test.py | 3 +- setup.py | 2 +- 4 files changed, 54 insertions(+), 10 deletions(-) create mode 100644 edk2toolext/capsule/Readme.md diff --git a/edk2toolext/capsule/Readme.md b/edk2toolext/capsule/Readme.md new file mode 100644 index 00000000..7c3ed730 --- /dev/null +++ b/edk2toolext/capsule/Readme.md @@ -0,0 +1,40 @@ +# Capsule Helper and Tools + +These modules are designed to help developers build, sign, and distribute correctly formatted +UEFI Capsules, as well as the Windows files necessary to arm and install the Capsules. + +## Capsule Helper Parameters + +The CapsuleHelper tool has a number of functions to help build and/or format Capsules +and their associated files. Each of these functions has some associated function documentation, +but there are some shared parameters between all of the functions. These are described here. + +### Capsule Options + +This is a dictionary that can include the following values: + +- `fw_version_string` - must be a string containing the dot-separated semantic version for this + capsule. Used in file naming and INF file +- `fw_version` - must be a number that can be represented as a 32-bit unsigned integer. Used in + the capsule binary and INF file +- `is_rollback` - TODO: Document +- `arch` - TODO: Document +- `fw_name` - TODO: Document +- `provider_name` - TODO: Document +- `esrt_guid` - TODO: Document +- `arch` - TODO: Document +- `fw_description` - TODO: Document +- `fw_version_string` - TODO: Document +- `fw_version` - TODO: Document +- `mfg_name` - TODO: Document +- `fw_integrity_file` - if included, must be the filename of a Mu FW integrity file to be included + with the capsule files. Caller must ensure that the integrity file is in the same directory as + the newly generated capsule binary. Used by the INF file + +### Signer Options + +TBD + +### Signature Options + +TBD diff --git a/edk2toolext/capsule/capsule_helper.py b/edk2toolext/capsule/capsule_helper.py index 69acf101..617a5609 100644 --- a/edk2toolext/capsule/capsule_helper.py +++ b/edk2toolext/capsule/capsule_helper.py @@ -24,12 +24,12 @@ PKCS7_SIGNED_DATA_OID = '1.2.840.113549.1.7.2' -def get_capsule_file_name(capsule_options): +def get_capsule_file_name(capsule_options: dict) -> str: '''from the shared capsule_options dictionary, returns the formatted capsule file name''' return f"{capsule_options['fw_name']}_{capsule_options['fw_version_string']}.bin" -def get_normalized_version_string(version_string): +def get_normalized_version_string(version_string: str) -> str: '''takes in a version string and returns a normalized version that is compatible with inf and cat files''' # 19H1 HLK requires a 4 digit version string, or it will fail while (version_string.count('.') < 3): @@ -37,17 +37,18 @@ def get_normalized_version_string(version_string): return version_string -def get_default_arch(): +def get_default_arch() -> str: '''helper function to consistently return the default architecture for windows files''' return 'amd64' -def get_default_os_string(): +def get_default_os_string() -> str: '''helper function to consistently return the default os for windows files''' return 'Win10' -def build_capsule(capsule_data, capsule_options, signer_module, signer_options): +def build_capsule(capsule_data: bytes, capsule_options: dict, signer_module: object, + signer_options: dict) -> UefiCapsuleHeaderClass: ''' goes through all of the steps of capsule generation for a single-payload FMP capsule @@ -108,7 +109,7 @@ def build_capsule(capsule_data, capsule_options, signer_module, signer_options): return uefi_capsule_header -def save_capsule(uefi_capsule_header, capsule_options, save_path): +def save_capsule(uefi_capsule_header: UefiCapsuleHeaderClass, capsule_options: dict, save_path: str) -> str: ''' takes in a UefiCapsuleHeaderClass object, a dictionary of capsule_options, and a filesystem directory path and serializes the capsule object to the target directory @@ -130,7 +131,7 @@ def save_capsule(uefi_capsule_header, capsule_options, save_path): return capsule_file_path -def create_inf_file(capsule_options, save_path): +def create_inf_file(capsule_options: dict, save_path: str) -> str: ''' takes in a dictionary of capsule_options and creates the Windows INF file for the UEFI capsule according to the provided options @@ -156,6 +157,8 @@ def create_inf_file(capsule_options, save_path): capsule_options['fw_version'] ) infgenerator.Manufacturer = capsule_options['mfg_name'] + if 'fw_integrity_file' in capsule_options: + infgenerator.IntegrityFilename = os.path.basename(capsule_options['fw_integrity_file']) inf_file_path = os.path.join(save_path, f"{capsule_options['fw_name']}.inf") ret = infgenerator.MakeInf(inf_file_path, get_capsule_file_name(capsule_options), capsule_options['is_rollback']) if(ret != 0): @@ -164,7 +167,7 @@ def create_inf_file(capsule_options, save_path): return inf_file_path -def create_cat_file(capsule_options, save_path): +def create_cat_file(capsule_options: dict, save_path: str) -> str: ''' takes in a dictionary of capsule_options and creates the Windows CAT file for the UEFI capsule according to the provided options diff --git a/edk2toolext/tests/capsule/capsule_helper_test.py b/edk2toolext/tests/capsule/capsule_helper_test.py index 435b0bc3..ea89b83a 100644 --- a/edk2toolext/tests/capsule/capsule_helper_test.py +++ b/edk2toolext/tests/capsule/capsule_helper_test.py @@ -25,7 +25,8 @@ 'fw_name': 'TEST_FW', 'fw_version_string': '1.2.3', # deliberately use 3-part version to exercise version normalization. 'provider_name': 'TESTER', - 'fw_description': 'TEST FW' + 'fw_description': 'TEST FW', + 'fw_integrity_file': "IntegrityFile.bin" }, 'signer': { 'option2': 'value2', diff --git a/setup.py b/setup.py index 47bace3e..821875b5 100644 --- a/setup.py +++ b/setup.py @@ -78,7 +78,7 @@ def run(self): }, install_requires=[ 'pyyaml>=5.3.1', - 'edk2-pytool-library>=0.10.13', + 'edk2-pytool-library>=0.10.15', 'pefile>=2019.4.18' ], extras_require={