OEM Certificate Key Rolling

Secure Boot Certificate Key Rolling

Background: Industry-Wide Secure Boot Key Update

After 15 years of operation, the Secure Boot ecosystem is undergoing its first comprehensive certificate key rotation. This critical security update requires coordinated efforts across the entire technology ecosystem, including hardware manufacturers, operating system vendors, and firmware developers.

This industry-wide initiative ensures continued security and trust in the boot process while maintaining compatibility across diverse platforms and operating systems.

There are a few actions that are needed by the ecosystem (OEMs, IHVs, etc):

Update the factory defaults
Create a PK signed KEK payload
Contribute the PK signed KEK Payloads

Update Factory Defaults for OEMs

OEMs are asked to perform firmware updates that include the updated certificates in the factory defaults. These defaults are accessible through your platform's UEFI settings interface (BIOS menu).

Critical Requirements for OEMs

⚠️ CRITICAL: OEMs MUST NOT modify the active Secure Boot variables on a shipped production device during normal operation.

Do NOT change these active Secure Boot variables:

"PK" (Platform Key)
"KEK" (Key Exchange Key)
"db" (Signature Database)
"dbx" (Forbidden Signature Database)

Why this matters: Modifying these variables will break full disk encryption because they are key components of SRTM PCR measurements.

What OEMs Should Do Instead

Update factory defaults only: Modify the certificate templates in your firmware's factory default settings through a firmware update (Provide the firmware update through Windows Update, LVFS, or OEM specified update mechanism if applicable)
Preserve reset functionality: Ensure that when users reset Secure Boot through your OEM-specific mechanism, the correct updated certificates for your platform are applied
Follow OS compatibility guidelines: Implement the instructions below to ensure your certificates are properly recognized by operating systems (Windows, Linux) during system updates without breaking Full Disk Encryption

KEK Update Process Using SecureBoot Objects Repository

KEK Update Overview

This section provides example instructions for updating Key Exchange Keys (KEK) using the Microsoft SecureBoot Objects repository tools. These are not the only supported methods, and you are free to use your own tooling. Where possible this document will try to be OS agnostic. However Windows users are free to use Windows Tooling and Linux users are free to use fwupd or Linux Tooling.

This section is only an example of one method that may be used.

KEK Update Prerequisites

Clone the SecureBoot Objects Repository:

git clone https://github.com/microsoft/secureboot_objects.git
cd secureboot_objects

Install Python Dependencies:
```
pip install -r pip-requirements.txt
```
Required Certificates:
- Your Platform Key (PK)'s Private Key
- Access to the latest KEK certificates from the repository

Step 1: Download Required Components

You may use the repository's current unsigned release:

# Get the latest UNSIGNED release for KEK updates (OEMs need to sign with their own PK)
$latestVersion = "v1.5.1"  # Check releases page for current version (NOT the -signed version)
$architecture = "x64"  # architecture does not matter for certificates

# Download the unsigned release
Invoke-WebRequest -Uri "https://github.com/microsoft/secureboot_objects/releases/download/$latestVersion/edk2-$architecture-secureboot-binaries.zip" -OutFile "secureboot-unsigned.zip"
Expand-Archive -Path "secureboot-unsigned.zip" -DestinationPath ".\unsigned-release"

Step 2: Generate Signable KEK Update Using Repository Tools

Use the repository's auth_var_tool.py to create the signable content:

# Navigate back to the repository root
cd ..

# Create output directory
New-Item -ItemType Directory -Force -Path ".\kek-update"

# Generate the signable KEK update file
python .\scripts\auth_var_tool.py format KEK 8be4df61-93ca-11d2-aa0d-00e098032b8c "NV,BS,RT,AT,AP" .\unsigned-release\MicrosoftAndThirdParty\Firmware\KEK.bin --timestamp 2010-03-06T19:17:21Z --output-dir .\kek-update

# This creates:
# - KEK.signable.bin (equivalent to using Format-SecureBootUEFI)
# - KEK.receipt.json (metadata for signature attachment)

Step 3: Sign the KEK Update

Absolutely DEFER to your signing team. This was not writen by an expert on signing and is only an example.

Option A: Direct Signing with PFX File (Not recommended)

# Sign directly with your Platform Key PFX file
python .\scripts\auth_var_tool.py sign KEK 8be4df61-93ca-11d2-aa0d-00e098032b8c "NV,BS,RT,AT,AP" .\unsigned-release\MicrosoftAndThirdParty\Firmware\KEK.bin --pfx-file .\path\to\your\PlatformKey.pfx --timestamp 2010-03-06T19:17:21Z --output-dir .\kek-update

Option B: External Signing (Recommended for Production)

Note: This option requires SignTool.exe from the Windows SDK

# Step 1: Create signable data (already done in Step 2)
# Step 2: Sign using SignTool (or Openssl or sbsign)
# Production method using certificate thumbprint from certificate store
signtool.exe sign /v /p7ce DetachedSignedData /p7co "1.2.840.113549.1.7.1" /fd SHA256 /sha1 <PlatformKey_Certificate_Thumbprint> /p7 .\kek-update .\kek-update\KEK.signable.bin

# Alternative: Using PFX file (less secure for production)
# signtool.exe sign /v /p7ce DetachedSignedData /p7co "1.2.840.113549.1.7.1" /fd SHA256 /f .\path\to\PlatformKey.pfx /p7 .\kek-update .\kek-update\KEK.signable.bin

# Step 3: Attach the signature using the receipt
python .\scripts\auth_var_tool.py sign --receipt-file .\kek-update\KEK.receipt.json --signature-file .\kek-update\KEK.signable.bin.p7 --output-dir .\kek-update

If you do not wish to download the full SDK you may download SignTool.exe on its own from the Symbol Server. However this is not recommended for production.

curl.exe -L -A "Microsoft-Symbol-Server/10.0.0.0" https://msdl.microsoft.com/download/symbols/signtool.exe/910D667173000/signtool.exe -o signtool.exe

Step 5: (Optional) Describe the KEK Update

You may use the auth_var_tool.py describe command to verify the payload that was just generated. The describe command will attempt to print out all available information contained in the binary file.

# Verify the created authenticated variable
python .\scripts\auth_var_tool.py describe .\kek-update\KEK.authvar.bin --output-dir .\kek-update

# Check the description file for correctness
Get-Content .\kek-update\KEK.authvar.bin.authvar.txt

Step 6: Apply the KEK Update

Ensure that your KEK payload works on a system you intend to target. This means that the system's platform key (the public certificate) matches the certificate used to sign.

Method 1: Using Windows (BitLocker-aware)

Requires: Administrator privileges and UEFI-compatible system

# Apply the KEK update
# Note: This command is BitLocker-aware and will handle PCR resealing automatically
Set-SecureBootUEFI -Name KEK -AppendWrite -ContentFilePath .\unsigned-release\MicrosoftAndThirdParty\Firmware\DefaultKek.bin -SignedFilePath .\kek-update\KEK.signable.bin.p7 -Time 2010-03-06T19:17:21Z

If the platform returns Incorrect authentication data: 0xC0000022 this means that signature validation failed and you will need to review that you used the correct timestamp, attributes, guid, etc.

Method 2: Using Linux (fwupd - Recommended)

Requires: Root privileges and fwupd installed

# Option A: Using fwupd (Recommended - Better UX)
# Install fwupd if not already available using your favorite package manager
sudo apt-get install fwupd        # Ubuntu/Debian
sudo dnf install fwupd            # Fedora/RHEL
sudo pacman -S fwupd              # Arch Linux

# Apply KEK updates automatically (if available through LVFS)
sudo fwupdmgr update

# Option B: Manual KEK installation for testing
# Install a specific KEK blob file
sudo fwupdtool install-blob ./kek-update/KEK.authvar.bin

# Option C: Using efivar (For custom tooling development)
# Install efitools if you need low-level EFI variable access
sudo apt-get install efitools     # Ubuntu/Debian
sudo efi-updatevar -f ./kek-update/KEK.authvar.bin KEK

Linux-specific considerations:

fwupd Integration: fwupd provides the best user experience and handles dependencies automatically
LVFS Distribution: KEK updates through fwupd can be distributed via the Linux Vendor Firmware Service (LVFS)
Encryption: Linux systems using LUKS encryption may require additional steps to reseal keys
Distribution-specific: Different Linux distributions may have varying tools and requirements

Common Linux errors:

Permission denied: Ensure you're running as root and Secure Boot allows variable updates
Operation not supported: Some older systems don't support runtime EFI variable updates
Invalid signature: Verify the KEK was signed with the correct Platform Key for your system
fwupd not available: Install fwupd or fall back to efivar tools for manual management

Step 7: Reboot

Step 8: Verification and Testing

Ensure that the new KEK certificate exists.

Method 1: Validate with Windows

# Option A: Using simple string matching of the "Get-SecureBootUefi" command
[System.Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI KEK).bytes) -match "Microsoft Corporation KEK 2K CA 2023"

# Option B: Install 3rd Party Application https://www.powershellgallery.com/packages/UEFIv2
Get-UEFISecureBootCerts KEK

Method 2: Validate with Linux

# Option A: Using fwupd (Recommended)
# Check fwupd security information including Secure Boot status
sudo fwupdmgr security

# List firmware and security devices
sudo fwupdmgr get-devices

# Option B: Using efivar (For detailed EFI variable inspection)
# Verify the KEK update was applied successfully
sudo efi-readvar -v KEK

# Alternative: Check EFI variables directly
ls -la /sys/firmware/efi/efivars/KEK-*
sudo hexdump -C /sys/firmware/efi/efivars/KEK-8be4df61-93ca-11d2-aa0d-00e098032b8c | head

OEM Contribution Overview

OEMs can contribute their Platform Key (PK) signed Key Exchange Keys (KEK) to this repository to ensure proper Secure Boot compatibility across different platforms and operating systems.

This section provides complete step-by-step instructions including all git commands needed, assuming no prior GitHub or git experience.

OEM Contribution Prerequisites

Before submitting, ensure you have:

Valid PK signed KEK payload (KEK Update): See Create a PK signed KEK payload
Test Results: Validation that your certificates work correctly with Windows and/or Linux boot processes
GitHub Account: You'll need a free GitHub account - create one at github.com/signup
Git Installed: Download and install git from git-scm.com

Complete Submission Process with Git Commands

Step 1: Validation Requirements

Before submitting, verify that your KEK update payload was successfully applied and tested on Windows and/or Linux. See Step 8: Verification and Testing above.

Step 2: Fork the Repository on GitHub

A "fork" creates your own copy of the repository where you can make changes.

Open your web browser and go to: https://github.com/microsoft/secureboot_objects
Sign in to your GitHub account (top right corner)
Click the "Fork" button (top right of the page, near the "Star" button)
Wait a few seconds - GitHub will create your fork at https://github.com/YOUR-USERNAME/secureboot_objects

Note: Replace YOUR-USERNAME with your actual GitHub username in all commands below.

Step 3: Clone Your Fork to Your Computer

Open PowerShell (or your preferred terminal) and run these commands:

# Navigate to where you want to store the repository
# For example, create a folder in your home directory:
cd ~
New-Item -ItemType Directory -Force -Path "github-repos"
cd github-repos

# Clone YOUR fork (replace YOUR-USERNAME with your GitHub username)
git clone https://github.com/YOUR-USERNAME/secureboot_objects.git

# Navigate into the cloned repository
cd secureboot_objects

# Add the original Microsoft repository as "upstream" (for getting updates)
git remote add upstream https://github.com/microsoft/secureboot_objects.git

# Verify your remotes are set up correctly
git remote -v
# You should see:
# origin    https://github.com/YOUR-USERNAME/secureboot_objects.git (fetch)
# origin    https://github.com/YOUR-USERNAME/secureboot_objects.git (push)
# upstream  https://github.com/microsoft/secureboot_objects.git (fetch)
# upstream  https://github.com/microsoft/secureboot_objects.git (push)

Step 4: Configure Git (First Time Only)

If this is your first time using git, configure your identity:

# Set your name (will appear in commit history)
git config --global user.name "Your Full Name"

# Set your email (use the email associated with your GitHub account)
git config --global user.email "[email protected]"

# Verify your configuration
git config --global --list

Step 5: Create a Feature Branch

Important: Never work directly on the main branch. Always create a new branch for your changes.

# Make sure you're on the main branch and it's up to date
git checkout main
git pull upstream main

# Create and switch to a new branch (replace <oem> with your company name, no spaces)
# Example: kek-update/contoso or kek-update/acmecorp
git checkout -b kek-update/<oem>

# Verify you're on the new branch
git branch
# The current branch will have an asterisk (*) next to it

Step 6: Add Your KEK Update Files

Now you'll add your PK-signed KEK update file to the repository.

Important: You'll need the certificate thumbprint from Step 7 to name your file correctly. If you haven't extracted it yet, skip to Step 7 first, then come back here.

# Create a directory for your OEM (replace YourOEMName with your company name)
# Use the exact company name as it should appear in the repository
New-Item -ItemType Directory -Force -Path "PostSignedObjects\KEK\YourOEMName"

# Copy your KEK update file(s) to the repository
# Replace the paths with your actual file locations
# Name format: KEKUpdate_YourOEMName_PK<first8charsOfThumbprint>.bin
# Example: KEKUpdate_Microsoft_PK38A346B8.bin (using first 8 chars of thumbprint)
# If you haven't extracted the thumbprint yet, use a temporary name and rename later
Copy-Item "C:\path\to\your\kek-update\KEK.authvar.bin" -Destination "PostSignedObjects\KEK\YourOEMName\KEKUpdate_YourOEMName_PK<thumbprint>.bin"

# Verify the file was copied
Get-ChildItem "PostSignedObjects\KEK\YourOEMName\KEKUpdate_*.bin"

Step 7: Extract Certificate Information

You need to extract information about your KEK update to add to the mapping file and to properly name your file:

# Navigate to the repository root if not already there
cd $HOME\github-repos\secureboot_objects

# Install Python dependencies if you haven't already
pip install -r pip-requirements.txt

# Extract certificate information from your KEK update
# If you haven't renamed your file yet, use the path where you originally placed it
python .\scripts\examples\get_auth_var_signing_certificate.py .\PostSignedObjects\KEK\YourOEMName\KEKUpdate_YourOEMName_PKTEMP.bin

# This will output information like:
# Certificate Subject: CN=Your Company PK
# Certificate Thumbprint: 38a346b84c0e230ca4f235e7355b872460770264
# Certificate Serial Number: 1234567890
# Valid From: 2023-01-01
# Valid To: 2033-01-01

Save this output - you'll need it for the next steps.

Now rename your file to include the first 8 characters of the thumbprint (uppercase):

# Using the thumbprint from the output above (first 8 characters, uppercase)
# Example: thumbprint is 38a346b84c0e230ca4f235e7355b872460770264
# First 8 chars: 38a346b8 → uppercase: 38A346B8
Rename-Item -Path "PostSignedObjects\KEK\YourOEMName\KEKUpdate_YourOEMName_PKTEMP.bin" -NewName "KEKUpdate_YourOEMName_PK38A346B8.bin"

# Verify the renamed file
Get-ChildItem "PostSignedObjects\KEK\YourOEMName\KEKUpdate_*.bin"

Step 8: Update the KEK Update Map File

You need to add your KEK update information to the kek_update_map.json file:

# Open the JSON file in your preferred editor
# For Notepad:
notepad .\PostSignedObjects\KEK\kek_update_map.json

# For VS Code (if installed):
code .\PostSignedObjects\KEK\kek_update_map.json

Add a new entry to the JSON file using this template. The key is the full certificate thumbprint (lowercase, from Step 7):

{
    "your_full_certificate_thumbprint_here_lowercase": {
        "KEKUpdate": "YourOEMName\\KEKUpdate_YourOEMName_PK<FIRST8CHARS>.bin",
        "Certificate": {
            "serial_number": 1234567890,
            "issued_to": "CN=Your Company Platform Key,O=Your Company Name,L=City,ST=State,C=Country",
            "issued_by": "CN=Your Company Platform Key,O=Your Company Name,L=City,ST=State,C=Country"
        }
    }
}

Important JSON formatting rules:

The key must be the full certificate thumbprint in lowercase (from Step 7 output)
The filename uses the first 8 characters of the thumbprint in uppercase: KEKUpdate_YourOEMName_PK<FIRST8CHARS>.bin
Use double backslashes (\\) in the file path
Add a comma after the previous entry if you're adding to the middle of the file
Ensure all quotes are straight quotes (") not curly quotes (" or ")
The serial_number should be a number (no quotes)
Save the file when done

Example of a complete entry:

{
    "8058e8cc51749652804bbd6f39aed713d119c64b": {
        "KEKUpdate": "Microsoft\\KEKUpdate_Microsoft_PK1.bin",
        "Certificate": {
            "serial_number": 171049019130091589582073331848314912,
            "issued_to": "CN=Microsoft Hyper-V Firmware PK,O=Microsoft Corporation,L=Redmond,ST=Washington,C=US",
            "issued_by": "CN=Microsoft Corporation Third Party Marketplace PCA,O=Microsoft Corporation,L=Redmond,ST=Washington,C=US"
        }
    }
}

Note: The thumbprint key (8058e8cc51749652804bbd6f39aed713d119c64b) is lowercase and full length, while the filename suffix (PK1) can use a numbering scheme or the first 8 characters of the thumbprint in uppercase (e.g., PK8058E8CC).

Step 9: Stage Your Changes

Tell git which files you want to include in your submission:

# Add your entire OEM directory with all KEK update files
git add PostSignedObjects\KEK\YourOEMName\

# Add the updated JSON mapping file
git add PostSignedObjects\KEK\kek_update_map.json

# Check what files are staged (should show your files in green)
git status

Step 10: Commit Your Changes

Create a commit with a clear message describing your changes:

# Commit with a descriptive message
git commit -m "[Secure Boot KEK Update] YourOEMName PK-Signed KEK Update"

# Verify the commit was created
git log -1

Step 11: Push Your Branch to GitHub

Upload your branch to your fork on GitHub:

# Push your branch to YOUR fork (origin)
git push origin kek-update/<oem>

# If this is the first push, you may see a message about setting upstream.
# The command may suggest running:
# git push --set-upstream origin kek-update/<oem>
# Run that command if prompted.

Step 12: Create a Pull Request on GitHub

Now create the pull request through the GitHub website:

Open your web browser and go to your fork: https://github.com/YOUR-USERNAME/secureboot_objects
You should see a yellow banner at the top saying "Your recently pushed branches" with a green "Compare & pull request" button
Click "Compare & pull request"
Fill out the pull request form:
- Title: [Secure Boot KEK Update] YourOEMName PK-Signed KEK Update
- Description: Use the template below
Click "Create pull request"

Pull Request Description Template

Copy and paste this into your pull request description, filling in your information:

## OEM Certificate Submission

**OEM Name**: [Your Company Name]
**Contact Email**: [[email protected]]

### Certificate Details
- **Platform Key Thumbprint**: [SHA-256 thumbprint]
- **Expiration Date**: [YYYY-MM-DD]

### Testing Completed
- [ ] Windows validation
- [ ] Linux validation

### Security Review
- [ ] No known security issues

### Additional Notes
[Any additional information about the certificates or implementation]

Review Process

Appropriate maintainers will review your submission and will notify internal and external counterparts to ensure that the package is distributed across Windows and Linux.

What Happens After You Submit

Automated Checks: GitHub may run automated checks on your pull request
Maintainer Review: Microsoft maintainers will review your submission
Feedback: You may receive comments or requests for changes
Approval: Once approved, maintainers will merge your contribution
Distribution: Your KEK update will be distributed through Windows and Linux update channels

Making Changes After Submission

If maintainers request changes to your pull request:

# Make sure you're on your branch
git checkout kek-update/<oem>

# Make the requested changes to your files

# Stage the changes
git add PostSignedObjects\KEK\YourOEMName\
git add PostSignedObjects\KEK\kek_update_map.json

# Commit the changes
git commit -m "Address review feedback: [describe what you changed]"

# Push the changes - they'll automatically update your pull request
git push origin kek-update/<oem>

Troubleshooting Common Git Issues

Problem: fatal: not a git repository

Solution: Make sure you're in the secureboot_objects directory:

cd $HOME\github-repos\secureboot_objects

Problem: error: failed to push some refs

Solution: Your fork may be out of date. Update it:

git checkout main
git pull upstream main
git checkout kek-update/<oem>
git rebase main
git push origin kek-update/<oem> --force-with-lease

Problem: merge conflict when rebasing

Solution: Contact the maintainers for assistance or start with a fresh branch:

git checkout main
git pull upstream main
git checkout -b kek-update/<oem>-v2
# Re-add your files and commit

Problem: Forgot to create a branch and worked on main

Solution: Create a branch from your current changes:

git checkout -b kek-update/<oem>
git push origin kek-update/<oem>

Support and Contact

For questions about the submission process:

Technical Issues: Open an issue in the repository
Security Concerns: Contact [email protected]
General Questions: Use the repository discussions

OEM Certificate Key Rolling

OEM Certificate Key Rolling

Secure Boot Certificate Key Rolling

Background: Industry-Wide Secure Boot Key Update

Update Factory Defaults for OEMs

Critical Requirements for OEMs

What OEMs Should Do Instead

KEK Update Process Using SecureBoot Objects Repository

KEK Update Overview

KEK Update Prerequisites

Step 1: Download Required Components

Step 2: Generate Signable KEK Update Using Repository Tools

Step 3: Sign the KEK Update

Option A: Direct Signing with PFX File (Not recommended)

Option B: External Signing (Recommended for Production)

Step 5: (Optional) Describe the KEK Update

Step 6: Apply the KEK Update

Method 1: Using Windows (BitLocker-aware)

Method 2: Using Linux (fwupd - Recommended)

Step 7: Reboot

Step 8: Verification and Testing

Method 1: Validate with Windows

Method 2: Validate with Linux

OEM Contribution Overview

OEM Contribution Prerequisites

Complete Submission Process with Git Commands

Step 1: Validation Requirements

Step 2: Fork the Repository on GitHub

Step 3: Clone Your Fork to Your Computer

Step 4: Configure Git (First Time Only)

Step 5: Create a Feature Branch

Step 6: Add Your KEK Update Files

Step 7: Extract Certificate Information

Step 8: Update the KEK Update Map File

Step 9: Stage Your Changes

Step 10: Commit Your Changes

Step 11: Push Your Branch to GitHub

Step 12: Create a Pull Request on GitHub

Pull Request Description Template

Review Process

What Happens After You Submit

Making Changes After Submission

Troubleshooting Common Git Issues

Support and Contact

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally