[Documentation]: Add instructions for signing the files (via signtool, etc.)

[miketheitguy]

Request Description

This might be out of scope here, but either a script or some documentation on signing the secure boot files could be useful.

I've been evaluating using this repo and scripts to:

• Manually update my systems to avoid CVE-2023-24932. Basically to accelerate the enforcement phase for CVE-2023-24932 of our systems out of the box. This includes the entire mitigation process as automated signed files (custom PK/KEK)
• Custom Secure Boot Key integration (PK + KEK + DB)
• I'll include the vendor keys as-needed

So having some sort of end-to-end process to do all of this would be fantastic :)

My plan is to integrate this into an entire pipeline for our systems.

Are you going to make the change?

I will make the change

Do you need maintainer feedback?

No maintainer feedback needed

Anything else?

No response

[Flickdm]

Hey @miketheitguy!

I've done a quick search of Microsoft Learn for good documentation for the full chain and I haven't found anything I'm satisfied with yet. The closest I've found is Appendix B: Scripts for enabling Secure Boot with NULL db which is close to what you're asking for but not exactly.

The best public documentation I've found on this topic actually comes from the NSA's CTR-UEFI-SECURE-BOOT-CUSTOMIZATION-20200915.PDF.

I'm not against documenting the end to end process as I do think this is something that should be well understood. As I understand the issue are you planning to document this?

[Flickdm]

Just to mentioned edk2-pytool-library has a function you can use to create the authenticated payloads that are required for servicing.

[JohnAZoidberg]

I'm curious about this, too.

I'm not against documenting the end to end process as I do think this is something that should be well understood. As I understand the issue are you planning to document this?

As far as I understand Microsoft publishes the signed dbx update file that everybody in the industry uses.
The UEFI Forum now refers to this repository instead of publishing dbx on their website.

So the official dbx update is generated by the scripts in this repository.
I assume there is only one extra step - Microsoft taking the output from github actions, signing it and releasing it.
Is that correct?

I'm also curious how Microsoft does that signing step and then how to manually apply the dbx .bin file.
I can't figure out how to make the documentation work: https://learn.microsoft.com/en-us/powershell/module/secureboot/set-securebootuefi
Not with my own files, neither with the files from this repository.
That documentation mentions signtool.

[Flickdm]

@JohnAZoidberg

As far as I understand Microsoft publishes the signed dbx update file that everybody in the industry uses.
The UEFI Forum now refers to this repository instead of publishing dbx on their website.

Accurate, those payloads are signed using the authority of the Microsoft 2011 KEK Certificate. Eventually once the 2011 KEK can no longer authorize payloads the 2023 KEK will be used.

So the official DBX update is generated by the scripts in this repository.

A binary identical version is produced internally due to build restrictions, and due to needing to test this before release. This repo is ensuring that they can be reproduced and publicly documenting them.

Those are the unsigned binaries release that are literally just EFI_SIGNATURE_LISTS that contain the list of hashes. These can actually be used in firmware to enable secure boot or via the OS to enable it.

These are not Authenticated variables which I will discuss next.

I assume there is only one extra step - Microsoft taking the output from github actions, signing it and releasing it.
Is that correct?

Mostly - we actually create them ahead of time internally to prepare for patch tuesday and then update this repo later to announce and make them publicly available. The signed versions are just UEFI Spec defined EFI_VARIABLE_AUTHENTICATION_2 Authenticated variables payloads as defined in secure boot.

The format of EFI_VARIABLE_AUTHENTICATION_2 can be broken down like so:

[EFI_TIME][WIN_CERTIFICATE][SIGNATURE][DATA]
    |            |             |        |
    |            |             |         `---- Variable Size
    |            |              `------------- Variable Size
    |             `--------------------------- Fixed Size
     `---------------------------------------- Fixed Size

 Where SIGNATURE = Asn.1 `SignedData` object or `ContentInfo` object
 And DATA = EFI_SIGNATURE_LIST

So it's really just the EFI_VARIABLE_AUTHENTICATION_2 header on top of our EFI_SIGNATURE_LIST.

The signature is actually a signature on a few fields concatenated together not just the raw data.

        name.encode("utf_16_le")
        + guid.bytes_le
        + efi_attributes.encode()
        + self.authenticated_variable.time.encode()
        + payload

You would use signtool + Format-SecureBootUefi or a authenticated variable builder function found here (I need to put up an example on how to use this function..) to create the authenticated variable header

---

So given the structure of the Authenticated Variable payload I suspect you're running into an issue where you're not passing the data in the correct form due to an assumption made in the powershell cmdlet that isn't clear.

Normally those authenticated variables are passed through a function like SetFirmwareEnvironmentVariableExW which has the function definition:

BOOL SetFirmwareEnvironmentVariableExW(
  [in] LPCWSTR lpName,
  [in] LPCWSTR lpGuid,
  [in] PVOID   pValue,
  [in] DWORD   nSize,
  [in] DWORD   dwAttributes
);

This function expects a pointer to the data as a whole.

However, this isn't the expectation of Set-SecureBootUEFI. This function actually expects the EFI_SIGNATURE_LIST and the EFI_VARIABLE_AUTHENTICATION_2 header to be pass as two seperate files.

So to seperate them back up you'll likely have to use something like SplitDbxContent (or do the math yourself)

And then you can use a command like the following:

Set-SecureBootUefi -Name dbx -ContentFilePath .\content.bin -SignedFilePath .\signature.p7 -Time 2010-03-06T19:17:21Z -AppendWrite

Check out that PDF I posted it goes into a lot of useful detail! If you have additional questions feel free to add them and I'll answer them as soon as I can.

[JohnAZoidberg]

First of all thanks for the detailed answer, I appreciate it!

So the official DBX update is generated by the scripts in this repository.

A binary identical version is produced internally due to build restrictions, and due to needing to test this before release. This repo is ensuring that they can be reproduced and publicly documenting them.

I think it's great that you guys are doing it like this, it's good to know how the unsigned binary was created.
Both for making our own and for trusting what Microsoft provides.

Those are the unsigned binaries release that are literally just EFI_SIGNATURE_LISTS that contain the list of hashes. These can actually be used in firmware to enable secure boot or via the OS to enable it.

Ah this will only work if I delete all secureboot variables going into setup mode and enroll my own PKI.
But it's good to see the script. This is the first time I see Set-SecureBootUEFI without having to pipe anything into it.
I can't do that because I need to call Format-SecureBootUEFI on a different system than where I apply it.

You would use signtool + Format-SecureBootUefi or a authenticated variable builder function found here (I need to put up an example on how to use this function..) to create the authenticated variable header

Thanks, yes an example or a script to use as a commandline application would be great.
Something to replace Format-SecureBootUEFI or the linux tools.

So given the structure of the Authenticated Variable payload I suspect you're running into an issue where you're not passing the data in the correct form due to an assumption made in the powershell cmdlet that isn't clear.

I created

Normally those authenticated variables are passed through a function like SetFirmwareEnvironmentVariableExW which has the function definition:

BOOL SetFirmwareEnvironmentVariableExW(
[in] LPCWSTR lpName,
[in] LPCWSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
This function expects a pointer to the data as a whole.

However, this isn't the expectation of Set-SecureBootUEFI. This function actually expects the EFI_SIGNATURE_LIST and the EFI_VARIABLE_AUTHENTICATION_2 header to be pass as two seperate files.

So to seperate them back up you'll likely have to use something like SplitDbxContent (or do the math yourself)

And then you can use a command like the following:

Set-SecureBootUefi -Name dbx -ContentFilePath .\content.bin -SignedFilePath .\signature.p7 -Time 2010-03-06T19:17:21Z -AppendWrite

I used Format-SecureBootUEFI and signtool to create both files. Then when I want to load it:

PS C:\Users\skype\Downloads\dbx_8b5d9528> Set-SecureBootUEFI -SignedFilePath .\dbx.bin.p7 -Name dbx -ContentFilePath .\dbx.bin -Time 2011-11-01T13:30:00
Set-SecureBootUEFI : Incorrect authentication data: 0xC0000022
At line:1 char:1
+ Set-SecureBootUEFI -SignedFilePath .\dbx.bin.p7 -Name dbx -Cont ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : PermissionDenied: (Microsoft.Secur...BootUefiCommand:SetSecureBootUefiCommand) [Set-Secu
   reBootUEFI], UnauthorizedAccessException
    + FullyQualifiedErrorId : SetFWVarFailed,Microsoft.SecureBoot.Commands.SetSecureBootUefiCommand

Then I tried a different approach to create the signed dbx using linux tools and split it as you suggested, same error:

PS C:\Users\skype\Downloads\dbx_linux_fe9401e1> SplitDbxContent.ps1 .\dbx.bin
Successfully created output file .\signature.p7
Successfully created output file .\content.bin
PS C:\Users\skype\Downloads\dbx_linux_fe9401e1> Set-SecureBootUEFI -SignedFilePath .\signature.p7 -Name dbx -ContentFilePath .\content.bin -Time 2011-11-01T13:30:00
Set-SecureBootUEFI : Incorrect authentication data: 0xC0000022
At line:1 char:1
+ Set-SecureBootUEFI -SignedFilePath .\signature.p7 -Name dbx -ContentF ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : PermissionDenied: (Microsoft.Secur...BootUefiCommand:SetSecureBootUefiCommand) [Set-SecureBootUEFI], UnauthorizedAccessException
    + FullyQualifiedErrorId : SetFWVarFailed,Microsoft.SecureBoot.Commands.SetSecureBootUefiCommand

On this system I have Microsoft's 2011 and 2023 KEK enrolled, as well as a custom KEK that I am signing this dbx update with.
Does Set-SecureBootUEFI accept variables not signed by microsoft?

On linux using sudo efi-updatevar -a -f dbx.bin dbx works just fine.

Check out that PDF I posted it goes into a lot of useful detail! If you have additional questions feel free to add them and I'll answer them as soon as I can.

Unfortunately the PDF assumes that I run signtool on the same system where I apply the updates - but I need to keep the key on a different airgapped system. The PDF tells me to pipe powershell variables from one step into the next.

[JohnAZoidberg]

I was able to use Set-SecureBootUEFI with the artifact from this repo's release page

PS C:\Users\Daniel\Downloads\edk2-2011-signed-secureboot-binaries\amd64> SplitDbxContent.ps1 .\DBXUpdate.bin
Successfully created output file .\signature.p7
Successfully created output file .\content.bin

PS C:\Users\Daniel\Downloads\edk2-2011-signed-secureboot-binaries\amd64> Set-SecureBootUefi -Name dbx -ContentFilePath .\content.bin -SignedFilePath .\signature.p7 -Time 2010-03-06T19:17:21Z -AppendWrite

Name Bytes             Attributes
---- -----             ----------
dbx  {218, 7, 3, 6...} NON VOLATILE...

I'm not sure what's wrong with my dbx file.
This is how I generate it:

Format-SecureBootUEFI `
  -Name DBX `
  -Algorithm SHA256 `
  -SignatureOwner 6841bdb0-b2af-4079-918f-fe458325d5cd `
  -Hash `
    "2944DA098861619E21B522A642235BB2EC189FF20EF96E100B2FFDD9A39C3416", `
    "665B26AD26C1D739720A2793ACAEFBD8B6C16A599B48DCDBF594640522744483" `
  -SignableFilePath out\dbx.bin `
  -Time 2010-03-06T19:17:21Z `
  -AppendWrite `
  | Format-List

# Must sign with PK or KEK
& ".\thirdparty\signtool.exe" `
  sign /fd sha256 `
  /p7 .\ /p7co 1.2.840.113549.1.7.1 /p7ce DetachedSignedData /a `
  /f "kek_privkey.pfx" `
  out\dbx.bin

[Flickdm]

So at first glance, this looks correct? Although to be honest I'm not super familiar with the powershell scripts. I'll see if I can find some time to reproduce what you're seeing.

I put up a draft PR to add some basic debug tooling. The script might be helpful but it looks like it will require a change in edk2-pytool-lib to be completely helpful

If you can get that script working the output from the subcommand "describe" might be interesting as it will print the signature to compare against a working version.

[JohnAZoidberg]

Although to be honest I'm not super familiar with the powershell scripts.

I'll take anything as long as it works :D
I'm just struggling to figure out how to update dbx on windows.
On Linux I'm already able to do it.

Thanks, I tried it like this:

python secureboot_objects_microsoft/scripts/auth_var_tool.py \
  sign \
  dbx d719b2cb-3d3a-4596-a3bc-dad00e67656f "NV,BS,RT,AT" \
  dbx.esl kek.pfx \
  --output-dir .
> python secureboot_objects_microsoft/scripts/auth_var_tool.py \
    describe dbx.authvar.bin
INFO:root:Output: ./dbx.authvar.txt
EfiSignatureList
  Signature Type:        c1c41626-504c-4092-aca9-41f936934328
  Signature List Size:   7c
  Signature Header Size: 0
  Signature Size:       30
  Signature Header:      NONE
EfiSignatureData - EfiSignatureDataEfiCertSha256
  Signature Owner:      605dab50-e046-4300-abb6-3dd810dd8b23
  Signature Data: 2944DA098861619E21B522A642235BB2EC189FF20EF96E100B2FFDD9A39C3416
EfiSignatureData - EfiSignatureDataEfiCertSha256
  Signature Owner:      605dab50-e046-4300-abb6-3dd810dd8b23
  Signature Data: 665B26AD26C1D739720A2793ACAEFBD8B6C16A599B48DCDBF594640522744483

And then split it, but with Set-SecureBootUefi as above, Im still getting the same error.
Note that I'm not building on the same system as I'm applying on.

[JohnAZoidberg]

The edk2-2011-signed-secureboot-binaries/amd64/DBXUpdate.bin file available from the release page, how was that created? I can't figure out by looking at the repo how that file was created and then signed. That's what I'm trying to do but with my own hashes.

Was that created by python scripts/secure_boot_default_keys.py --keystore Templates/LegacyFirmwareDefaults.toml -o FirmwareArtifacts?

---

I created my own template.toml now and got the file from out/X64/foo/Imaging/DefaultDbx.bin.
I signed it with signtool same as above and tried to use set-securebootuefi but still "Incorrect authentication data".

[Flickdm]

Ah okay I think I know what is going on but I havent had a chance to actually try it! So to be clear you cannot sign the results from the output in this repo directly.

This actually goes back to this comment I left initially.

The signature is actually a signature on a few fields concatenated together not just the raw data.

        name.encode("utf_16_le")
        + guid.bytes_le
        + efi_attributes.encode()
        + self.authenticated_variable.time.encode()
        + payload

The to-be-signed component is really the above fields concatenated together and then signed.

So your powershell command you wrote is actually slightly incorrect and should be the following:

Format-SecureBootUEFI `
  -Name DBX `
  -Algorithm SHA256 `
  -SignatureOwner 6841bdb0-b2af-4079-918f-fe458325d5cd `
  -Hash `
    "2944DA098861619E21B522A642235BB2EC189FF20EF96E100B2FFDD9A39C3416", `
    "665B26AD26C1D739720A2793ACAEFBD8B6C16A599B48DCDBF594640522744483" `
  -SignableFilePath out\to_be_signed.bin `
  -ContentFilePath out\dbx.bin `
  -Time 2010-03-06T19:17:21Z `
  -AppendWrite `
  | Format-List

Here we added an additional field called "ContentFilePath" which is the EFI_SIGNATURE_LIST and "-SignableFilePath" now refers to something we can "sign"

Then you can sign the to-be-signed content

# Must sign with PK or KEK
& ".\thirdparty\signtool.exe" `
  sign /fd sha256 `
  /p7 .\ /p7co 1.2.840.113549.1.7.1 /p7ce DetachedSignedData /a  `
  /f "kek_privkey.pfx" `
  out\to_be_signed_dbx.bin

Then you can take the signed portion and set it like:

Set-SecureBootUEFI  -Name DBX  -Time 2010-03-06T19:17:21Z  -ContentFilePath dbx.bin -SignedFilePath to_be_signed.bin.p7   -AppendWrite 

This command will stich back up the two parts into the EFI_VARIABLE_AUTHENTICATION_2 mentioned above.

This is why my script has a "sign" command since it will perform all of this internally and concatenate the two parts together.

Let me know if that doesn't work!

[JohnAZoidberg]

So to be clear you cannot sign the results from the output in this repo directly.

Right.. that's what I thought - but I think that's the original question of the issues here.
You build some binaries from this repository but it's unclear how to get from those to the signed binaries that you release.

Let me know if that doesn't work!

It does!! Thanks so much. -ContentFilePath was the missing key.

[Flickdm]

Fair points! Thanks for the feedback I think this highlights something I can improve on. Technically this repo was set up to assist firmware engineers who generally do not need to sign a thing they're installing. That being said, I think it's fair to say this repo has evolved since that point and I think from this discussion I can come up with some tooling / documentation that will assist with this!