[Documentation]: Guidance for OEM self-generation of Secure Boot variable contents and append updates

[dinhngtu]

Request Description

Hello,

We're using secureboot_objects to generate our own KEK/db/dbx contents for VMs running on the XCP-ng hypervisor. During this process, we've run into a few issues:

• e64d1a5 has changed all current templates to point to dbx_info_msft_latest.json instead of recommending to ship an empty dbx by default. Is this an intentional change?
• LegacyFirmwareDefaults.toml suggests to use our own signature owner GUID. Yet WHCP instructs that the MS GUID be used for KEK, without a mention of timestamp. So what's the signature owner and timestamp we should use in our generated SB databases (KEK/db/dbx)?
• Self-generated dbx databases are not append-compatible with the signed versions. In other words, even if we shipped our own dbx, Windows will append its own signed database to the dbx variable. This would quickly consume all of the dbx variable's available space and cause subsequent updates to fail. Do you have any guidance on how to avoid this issue?
• Similarly, are the signed versions append-compatible with what Windows uses to update the dbx? Will there be issues with duplicate EFI_SIGNATURE_DATA if the signed version was shipped?

A final note: We hope that the Secure Boot objects could be shipped under a permissive license (e.g. BSD) that allows us to ship these objects in open-source projects.

Are you going to make the change?

Someone else needs to make the change

Do you need maintainer feedback?

Maintainer feedback requested

Anything else?

No response

[Flickdm]

Request Description

Hello,

We're using secureboot_objects to generate our own KEK/db/dbx contents for VMs running on the XCP-ng hypervisor. During this process, we've run into a few issues:

• e64d1a5 has changed all current templates to point to dbx_info_msft_latest.json instead of recommending to ship an empty dbx by default. Is this an intentional change?

This is an intentional change, while this is a goal we want to strive for the decision was made to not use an "empty dbx" for now while work in windows is being done to support OOBE dbx updates.

Actually you do raise a good point though - since the 2023 KEK has not actually revoked anything those hashes are unnecessary. I'm going to follow up here.

• LegacyFirmwareDefaults.toml suggests to use our own signature owner GUID. Yet WHCP instructs that the MS GUID be used for KEK, without a mention of timestamp. So what's the signature owner and timestamp we should use in our generated SB databases (KEK/db/dbx)?

# The Signature Lists are used to store the signature database in the UEFI Secure Boot Database
# Each entry must have a "SignatureOwner" GUID. While the GUID is not required to be unique,
# the Microsoft HLK test will fail if the GUID overlaps with the Microsoft GUID.
# It is recommended to use your own GUID for the SignatureOwner.
#

So you're referencing this section, I admit I can understand your confusion. To be more clear, if it's coming from Microsoft it should be using the Microsoft signature owner "77fa9abd-0359-4d32-bd60-28f4e78f784b". For anything that isn't coming from us it should be using your own.

# If the material is coming from Microsoft, unless otherwise stated the signature owner should be "77fa9abd-0359-4d32-bd60-28f4e78f784b"
# It is recommended to use your own GUID for the SignatureOwner for your own certificates and revocations.

I'll take an action item to update this to be more clear .

• Self-generated dbx databases are not append-compatible with the signed versions. In other words, even if we shipped our own dbx, Windows will append its own signed database to the dbx variable. This would quickly consume all of the dbx variable's available space and cause subsequent updates to fail. Do you have any guidance on how to avoid this issue?

As along as you use the signature owner mentioned above, Windows and Linux will apply the payload using the "APPEND" attribute.

Before appending, this payload will go through FilterSignatureList(..) in firmware.

The important line in question is line 1111

if (CompareMem (NewCert, Cert, CertList->SignatureSize) == 0) {

Here Cert is really EFI_SIGNATURE_DATA

  typedef struct _EFI_SIGNATURE_DATA {
    EFI_GUID                 SignatureOwner;
    UINT8                    SignatureData [_];
  }   EFI_SIGNATURE_DATA;

The SignatureData structure contains both the signature owner and the signature data.

Thus when the CompareMem(..) operates it will see that both the SignatureOwner and SignatureData match and throw away duplicates.

• Similarly, are the signed versions append-compatible with what Windows uses to update the dbx? Will there be issues with duplicate EFI_SIGNATURE_DATA if the signed version was shipped?

Nope for the reason listed above as long as the SignatureOwners match, the filtering behavior should work.

A final note: We hope that the Secure Boot objects could be shipped under a permissive license (e.g. BSD) that allows us to ship these objects in open-source projects.

Last I recall, someone was requested this and we were waiting for feedback for our company lawyers. I don't know if they've responded but I can look into it

Are you going to make the change?

Someone else needs to make the change

Do you need maintainer feedback?

Maintainer feedback requested

Anything else?

No response

[dinhngtu]

Thank you very much for the valuable information. Also, could you please document isOptional in HashesJsonSchema.json? It's already described at #279, but it'd be better to have official documentation on this field.

[Flickdm]

FYI waiting on https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-secure-boot-key-creation-and-management-guidance?view=windows-11#16-uefi-secure-boot-configuration-requirements-for-windows-11-version-25h2-devices to have updated guidance