The project contains command line Python scripts to stitch sub-region images to Intel FirmWare Image (IFWI) and create UEFI capsule images. Optionally, signing tool is included to generate signed sub-region image.

It supports Windows 10, Ubuntu Linux, or Yocto Linux.

• Firmware and BIOS Utilities (FBU)
  • Guidelines for Using Signing Keys
  • Installation
  • Usage
    • Sub-region capsule tool
      • JSON Input Format
      • Certificate files
      • Create capsule image
    • Stitching tool
    • Signing tool
  • License

SIIP tools supports signing method using asymmetric algorithms with RSA key. The following guidelines should be followed in performing digital signatures:

• RSA-3072 with hash function SHA384,512 and message formatting PSS
• Use appropriately sized keys and key parameters
  • For Integer Factorization or Discrete Logarithm algorithms use modulus size of at least 3072 bits.
  • Use RSA public exponent value equal to 65537
  • Use approved curve for EC algorithms: NIST P-384, NIST P-521 or Ed448

NOTE: This repository does NOT provide any keys for security reasons.

• Install Python v3.6 and additional modules

pip install -r requirements.txt

• Install openssl

Manually install OpenSSL to the host and add it to the system environment variable PATH.

Pre-compiled OpenSSL for Windows can be downloaded from here. You may use apt-get to install openssl on Ubuntu Linux.

Input file to run sub-region capsule requires a JSON format that describes the data structure and field values to be serialized into binary format.

Format of the JSON payload descriptor file:

  {
     "FmpGuid": <string (GUID)>,
     "Version": <integer>,
     "FV" :
     {
       "FvGuid": <string (GUID)>,
       "FfsFiles":
       [
         {
          "FileGuid": <string (GUID)>,
          "Compression": <boolean>,

          "signingKey": <string (file)>,
          "VendorGuid": <string (GUID)>,
          "signerType": <string (pkcs7 or rsa)>,

          "Data" :
          [
             [<string (member_name)>, <string (data_type)>, <integer (byte_size)>, <integer|string (member_value)>],
            ...
          ]
        }
      ]
    }
  }

Supported data_type values are "DECIMAL", "HEXADECIMAL", "STRING" or "FILE".

signingKey is optional, but if set VendorGuid and signerType must be set as well and then subregion will be built from Data and signed using signingKey, VendorGuid, and signerType.

If the signed capsule is required, you shall provide certificates from the command line. For testing purpose, they can be downloaded from here.

TestCert.pem
TestSub.pub.pem
TestRoot.pub.pem

NOTE: if certificate files does not match the ones built in BIOS, the capsule cannot be updated.

NOTE: JSON_FILE should be obtained from the owners of sub-region data.

$ python3 subregion_capsule.py -o capsule.out.bin -s TestCert.pem -p TestSub.pub.pem -t TestRoot.pub.pem <JSON_FILE>

Output messages :
Read binary input file ./SubRegionFv.fv
FMP_PAYLOAD_HEADER.Signature              = 3153534D (MSS1)
FMP_PAYLOAD_HEADER.HeaderSize             = 00000010
FMP_PAYLOAD_HEADER.FwVersion              = 00000001
FMP_PAYLOAD_HEADER.LowestSupportedVersion = 00000000
...
...
EFI_CAPSULE_HEADER.CapsuleImageSize = 00001B5D
sizeof (Payload)                    = 00001B3D
Write binary output file capsule.out.bin
Success

The capsule file capsule.out.bin is generated and should be used as input file for fwupdate tool on the target device to trigger capsule update.

The stitch tool can change or merge a supported sub-region file inside a full IFWI image based on UEFI Firmware Volume format.

To get a list of supported sub-regions, run:

$ python3 siip_stitch.py -h

usage: siip_stitch [-h] -ip ipname [-k PRIVATE_KEY] [-v] [-o FileName]
                   IFWI_IN IPNAME_IN

...
...
Supported Sub-Region Names: ['pse', 'fkm', 'tmac', 'tsnip', 'tsn', 'tcc',
'oob', 'oob_rootca', 'vbt', 'gop', 'gfxpeim']

To stitch a sub-region, provide the sub-region name (e.g. pse), IFWI image to be updated, and the sub-region file. For example:

$python3 siip_stitch.py -ip pse -o new.ifwi.bin ifwi.bin pse.bin

...
siip_stitch INFO *** Replacing pse ...
...
...
Decoding
Decoding
Decoding
Decoding
Decoding
Decoding
Decoding
Decoding
Create New FD file successfully.

Done!

The SIIP Signing tool generates security signatures and auxiliary data for a payload file. When BIOS loads the payload (code or data) during boot, it verifies the payload authenticity and integrity first.

For example, to sign an image with priv3k.pem which is a RSA-PSS private key with SHA384 hashing, run:

python3 siip_sign.py sign -i pse.bin -k priv3k.pem -s sha384 -m pss -o pse.signed.bin

The signed image (e.g. pse.signed.bin), is the input file to be either stitched into IFWI image, or for creating a capsule image for firmware update.

NOTE: SIIP signing tool supports only PSE firmware signing.

The Sub-region Signing tool allows users to generate a signed BIOS Sub-Region before loading it into the BIOS UEFI to enhance the security of the sub-region firmware.

For example, to sign a TCC sub-region provided by a vendor with the given Vendor GUID 7F6AD829-15E9-4FDE-9DD3-0548BB7F56F3 using RSA private key signing.pem, run:

python3 subregion_sign.py --name  tcc --signer signing.pem --signer_type rsa
                          --vendor-guid 7F6AD829-15E9-4FDE-9DD3-0548BB7F56F3
                          TccConfigData_Raw.bin --output TccConfigData_signed.bin

NOTE 1: Vendor GUID is specific value given by the vendor to the subregion being signed. Check BIOS implementation for the correct value.

NOTE 2: The Vendor GUID used above is a default non-production GUID for sub-region.

The signed image (e.g. TccConfigData_signed), is the input file to be either stitched into IFWI image, or for creating a capsule image for firmware update.

NOTE 3: Sub-region signing tool only test with a TCC sub-region. The PKCS#7 signing has not been tested at this time.

See LICENSE for details.