Skip to content

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

Open
Open
[Documentation]: Guidance for OEM self-generation of Secure Boot variable contents and append updates#281
Assignees
FlickdmSochiOgbuanya
Labels
state:backlogIn the backlogstate:needs-maintainer-feedbackNeeds more information from a maintainer to determine next stepsstate:needs-triageNeeds to triaged to determine next stepstype:documentationImprovements or additions to documentation

Description

@dinhngtu
Tu Dinh (dinhngtu)
opened on Oct 28, 2025

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

Activity

  1. Tu Dinh (dinhngtu)
    added
    state:needs-triageNeeds to triaged to determine next steps
    type:documentationImprovements or additions to documentation
    on Oct 28, 2025
  2. mu-automation
    added
    state:needs-maintainer-feedbackNeeds more information from a maintainer to determine next steps
    state:needs-ownerNeeds an issue owner to be assigned
    on Oct 28, 2025

  3. Flickdm commented on Oct 28, 2025

    @Flickdm
    Doug Flick (Flickdm)
    on Oct 28, 2025
    Member

    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

  4. dinhngtu commented on Oct 28, 2025

    @dinhngtu
    Tu Dinh (dinhngtu)
    on Oct 28, 2025
    ContributorAuthor

    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.

  5. Doug Flick (Flickdm)
    self-assigned this
    on Nov 3, 2025
  6. mu-automation
    removed
    state:needs-ownerNeeds an issue owner to be assigned
    on Nov 3, 2025

  7. Flickdm commented on Nov 3, 2025

    @Flickdm
    Doug Flick (Flickdm)
    on Nov 3, 2025
    Member

    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

  8. Doug Flick (Flickdm)
    assigned
    SochiOgbuanya
    on Dec 16, 2025

  9. mu-automation commented on Dec 18, 2025

    @mu-automation
    mu-automationbot
    on Dec 18, 2025 – with Mu Automation
    Contributor

    This issue has been automatically marked as stale because it has not had activity in 45 days. It will be closed if no further activity occurs within 7 days. Thank you for your contributions.

  10. mu-automation
    added
    state:staleHas not been updated in a long time
    on Dec 18, 2025
  11. Michael Kubacki (makubacki)
    added
    state:backlogIn the backlog
    and removed
    state:staleHas not been updated in a long time
    on Dec 18, 2025

  12. Flickdm commented on Mar 26, 2026

    @Flickdm
    Doug Flick (Flickdm)
    on Mar 26, 2026
    Member

    #376

    FYI License has been changed to BSD for everything

  13. dinhngtu commented on Mar 26, 2026

    @dinhngtu
    Tu Dinh (dinhngtu)
    on Mar 26, 2026
    ContributorAuthor

    #376

    FYI License has been changed to BSD for everything

    Thanks, very glad to hear!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

state:backlogIn the backlogstate:needs-maintainer-feedbackNeeds more information from a maintainer to determine next stepsstate:needs-triageNeeds to triaged to determine next stepstype:documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions