path: root/content/post/so-you-want-to-dabble-with-secure-boot-keys.md

---
title: "So you want to dabble with Secure Boot keys?"
date: 2025-06-21
---
# So you want to dabble with Secure Boot keys?

You came to the right place.  This post gives a beginners guide to:

* The Secure Boot key hierarchy: PK, KEK, db, and dbx.
* What you should be aware of to grok `.esl` and `.auth` files.

This is useful to understand if you're looking to take control of the Secure
Boot key hierarchy on your own systems--a deployment option called *custom keys*.

But just to ensure we are all on the same page before diving into some details.
Secure Boot is a *verified boot* technology provided by UEFI.  This is pretty
much what it sounds like: before the firmware is willing to boot an operating
system image, it needs to be verified.  Such verification requires the operating
system image to be signed (digital signature) or allowlisted by (cryptographic)
hash.

Secure Boot is also somewhat related to a Linux kernel feature called
*lockdown*.  Depending on exactly which Linux kernel is used, lockdown may be
enabled *automatically* as a result of using Secure Boot.  In lockdown,
signature verification on the kernel and kernel modules are enforced.  Secure
Boot keys may be consulted also for this verification, but the devil is in the
[details](https://git.glasklar.is/system-transparency/project/documentation/-/blob/main/archive/2025-04-04-sb-notes.md?ref_type=heads#what-we-need-to-know-about-the-kernel)
here.

Instead of making a mega post that never gets published, I'll try to revisit
what you need to know about signing images and the kernel in a follow-up post.

## Key hierarchy

Secure Boot has a variable containing trusted keys and allowlisted hashes.  This
variable is called *the authorized signature database*, or *db* for short.
There is also a *forbidden signature database* called *dbx*.  I find the long
names a bit confusing, but what we're really talking about here is a place to
define what Secure Boot should base its trust on (db) and another place to
define what should no longer be trusted (dbx) *despite* what's in db.  You're
right to think of dbx as revocation.

As an example, suppose there are two operating system images `foo` and `bar`
signed by a key in db and `H(bar)` is in dbx.  Secure Boot would consider image
`foo` valid whereas bar would be invalid.  Suppose unsigned image `H(baz)` is in
db and not in dbx.  Secure boot would consider image `baz` valid.

If you want to update db or dbx, you can chose to *replace* or *append*.  If you
replace, the old values are completely replaced with the new values.  If you
append, the new values are appended to the existing values.  In a custom key
setup I don't see that much reason to bother with appending, but it's possible.

It would be a problem if anyone could update db or dbx.  Therefore, UEFI only
permits such updates if they are signed by a trusted key.  This trusted key
is in a Secure Boot variable called KEK.  This is short for *Key Exchange Key*,
which is yet another name I find a bit confusing.  It is possible to have
multiple keys in KEK.

Similar to db and dbx, KEK can also be updated.  It would be a problem if anyone
could update KEK.  (You see where this is going now.)  Therefore, UEFI will only
permit such updates if they are signed by a trusted key.  This trusted key is
called PK, short for *Platform Key*.  This is the root of the Secure Boot key
hierarchy.  To replace PK, UEFI requires the new key to be signed by the current
key.

Below is a figure summarizing the Secure Boot key hierarchy.

              +----------------+
              |      PK        |
              +----------------+
                      |
                      v
              +----------------+
              |      KEK       |
              +----------------+
               /            \
              v              v
    +---------------+  +----------------+
    |      db       |  |      dbx       |
    +---------------+  +----------------+

To be a bit more detailed about what each part of the hierarchy typically
stores:

  - PK: a single X.509 certificates with an RSA key.
  - KEK: X.509 certificates with RSA keys.
  - db: X.509 certificates with RSA keys *or* SHA256 hashes of images.
  - dbx: SHA256 hashes of either X.509 certificates or images to revoke.

The above is not exhaustive, but I'm sorry to inform you're stuck with RSA keys.

## EFI variables

PK, KEK, db, and dbx are stored as EFI variables on the main SPI flash.  If this
sounds like mumbo jumbo: in the same place that your UEFI firmware is stored,
there is a read+write region where variables can be persisted across boots.
UEFI runtime services make some of these variables accessible read-only to the
operating system.  Other variables may also be available for writing, either
with or without additional authentication.  PK, KEK, db, and dbx updates usually
require valid signatures (the only exception to this is in so-called *setup
mode*).

Try reading the EFI variable that shows if Secure Boot is on or off:

    $ hexdump -C /sys/firmware/efi/efivars/SecureBoot-8be4df61-93ca-11d2-aa0d-00e098032b8c
    00000000  06 00 00 00 00                                    |.....|
    00000005

The first four bytes are EFI metadata.  The final byte shows Secure Boot is off
(0).

Try reading the EFI variable that shows if Secure Boot setup mode is on or off:

    $ hexdump -C /sys/firmware/efi/efivars/SetupMode-8be4df61-93ca-11d2-aa0d-00e098032b8c
    00000000  06 00 00 00 01                                    |.....|
    00000005

The final byte says setup mode is on (1).  This means it is currently possible
to provision a new PK without having a valid signature.  Setup mode can be
enabled via the UEFI menu.  This resets the current Secure Boot key hierarchy (!).

Try reading PK, KEK, db, and dbx:

* /sys/firmware/efi/efivars/PK-8be4df61-93ca-11d2-aa0d-00e098032b8c
* /sys/firmware/efi/efivars/KEK-8be4df61-93ca-11d2-aa0d-00e098032b8c
* /sys/firmware/efi/efivars/db-d719b2cb-3d3a-4596-a3bc-dad00e67656f
* /sys/firmware/efi/efivars/dbx-d719b2cb-3d3a-4596-a3bc-dad00e67656f

On a system with Secure Boot enabled you might see something like this:

    $ hexdump -C /sys/firmware/efi/efivars/PK-8be4df61-93ca-11d2-aa0d-00e098032b8c
    00000000  27 00 00 00 a1 59 c0 a5  e4 94 a7 4a 87 b5 ab 15  |'....Y.....J....|
    00000010  5c 2b f0 72 12 03 00 00  00 00 00 00 f6 02 00 00  |\+.r............|
    00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
    00000030  30 82 02 e2 30 82 01 ca  a0 03 02 01 02 02 14 2e  |0...0...........|
    00000040  9c f5 6c d3 e2 aa a3 04  2b 37 c6 88 75 e1 6d 96  |..l.....+7..u.m.|
    00000050  19 f9 be 30 0d 06 09 2a  86 48 86 f7 0d 01 01 0b  |...0...*.H......|
    00000060  05 00 30 2b 31 0b 30 09  06 03 55 04 03 0c 02 50  |..0+1.0...U....P|
    00000070  4b 31 1c 30 1a 06 03 55  04 0a 0c 13 53 79 73 74  |K1.0...U....Syst|
    00000080  65 6d 20 54 72 61 6e 73  70 61 72 65 6e 63 79 30  |em Transparency0|
    00000090  1e 17 0d 32 35 30 36 31  35 31 35 33 37 33 39 5a  |...250615153739Z|
    000000a0  17 0d 33 35 30 36 31 33  31 35 33 37 33 39 5a 30  |..350613153739Z0|
    000000b0  2b 31 0b 30 09 06 03 55  04 03 0c 02 50 4b 31 1c  |+1.0...U....PK1.|
    000000c0  30 1a 06 03 55 04 0a 0c  13 53 79 73 74 65 6d 20  |0...U....System |
    000000d0  54 72 61 6e 73 70 61 72  65 6e 63 79 30 82 01 22  |Transparency0.."|
    000000e0  30 0d 06 09 2a 86 48 86  f7 0d 01 01 01 05 00 03  |0...*.H.........|
    000000f0  82 01 0f 00 30 82 01 0a  02 82 01 01 00 a9 db 0b  |....0...........|
    00000100  52 89 cc 20 58 e5 71 da  24 9e 18 20 c6 33 8c 78  |R.. X.q.$.. .3.x|
    00000110  f0 32 85 d5 c6 57 5d dc  34 cf 2f 79 e7 5f ce 46  |.2...W].4./y._.F|
    00000120  ed 47 b4 bb 26 f6 8a 17  84 ee ec a2 f7 92 34 92  |.G..&.........4.|
    00000130  de b1 26 07 d6 a7 2b d7  aa 6c 87 b0 5b 58 da bb  |..&...+..l..[X..|
    00000140  4d 30 b1 8b b6 44 96 50  96 b3 6c e7 3b ca eb 79  |M0...D.P..l.;..y|
    00000150  53 08 a6 bb 36 07 b1 8c  9f 0a 78 d7 6b 69 48 e7  |S...6.....x.kiH.|
    00000160  87 2f fd 9b bc 8d f5 fc  cc 8b fe b2 b7 fd 62 c7  |./............b.|
    00000170  99 0e f6 52 29 55 99 83  25 72 c8 5c 19 6b 17 12  |...R)U..%r.\.k..|
    00000180  e8 97 14 1f 8d 20 81 3f  3d 63 52 1a 2b bc 58 34  |..... .?=cR.+.X4|
    00000190  dd fa 6c 67 43 87 f3 2c  ac 87 b5 fd b6 b0 22 22  |..lgC..,......""|
    000001a0  6a a9 a8 81 64 1c 52 dc  82 4d c7 2e 98 af b0 fe  |j...d.R..M......|
    000001b0  4f ae 67 65 21 83 57 cb  7b 89 03 57 31 a1 16 ef  |O.ge!.W.{..W1...|
    000001c0  39 1e 52 80 3d 96 64 03  bc 7a f5 a7 4d 63 a9 ef  |9.R.=.d..z..Mc..|
    000001d0  b8 61 bd d3 80 0f 44 ed  42 64 3e e8 25 c5 64 24  |.a....D.Bd>.%.d$|
    000001e0  64 13 34 43 85 ac 00 a9  26 17 7a 57 c9 48 fb f9  |d.4C....&.zW.H..|
    000001f0  04 89 36 dc c7 d0 b1 38  cf 49 b2 d5 81 02 03 01  |..6....8.I......|
    00000200  00 01 30 0d 06 09 2a 86  48 86 f7 0d 01 01 0b 05  |..0...*.H.......|
    00000210  00 03 82 01 01 00 00 52  52 45 73 f7 ba 80 c5 6e  |.......RREs....n|
    00000220  13 b5 45 0a 96 57 36 fd  ea 47 8f 1a a8 b1 59 bf  |..E..W6..G....Y.|
    00000230  6a ef 4d 21 92 ea b8 f3  7e 20 7b b6 30 58 18 e3  |j.M!....~ {.0X..|
    00000240  9e 18 2c 85 18 ca 1c 6f  fc 18 80 3b d0 e3 13 f2  |..,....o...;....|
    00000250  aa 8d 87 76 cb 4d 50 01  3d 54 71 2c f4 25 1a 05  |...v.MP.=Tq,.%..|
    00000260  cc 9e 7d dd 0e 61 ce 14  ce 6d 78 9d 75 12 75 4e  |..}..a...mx.u.uN|
    00000270  b4 87 fa 19 3b 5d 73 c7  ab 54 f1 ae 65 c1 7e 9e  |....;]s..T..e.~.|
    00000280  31 5b 16 48 2e 88 19 30  91 5a 2c 8c 33 1c eb 17  |1[.H...0.Z,.3...|
    00000290  9e 4b 44 10 70 61 72 88  b6 cb 28 d0 c4 bc 96 43  |.KD.par...(....C|
    000002a0  36 88 f6 67 0d 93 3a 0c  11 4b f6 73 e9 0f a0 b5  |6..g..:..K.s....|
    000002b0  58 4c da d4 4f 02 4e 19  dd df 4e 44 f0 6f 3b 90  |XL..O.N...ND.o;.|
    000002c0  c9 ff d7 64 cc 4a 9e c5  93 86 29 41 17 21 37 db  |...d.J....)A.!7.|
    000002d0  80 1f be 24 a3 a3 62 07  b5 e2 d0 d8 21 fd 9c 09  |...$..b.....!...|
    000002e0  95 2f 26 5f c3 60 45 86  e0 36 61 2a e7 8c 1b 49  |./&_.`E..6a*...I|
    000002f0  33 eb 10 49 bb 3c 80 f5  76 8a 1c 4c 3f 9e a2 d3  |3..I.<..v..L?...|
    00000300  c1 dd d6 3a 5b 63 b7 fb  72 ac 93 4e f1 f7 e2 e8  |...:[c..r..N....|
    00000310  3a 1b f9 19 6a 4b                                 |:...jK|
    00000316

You may have noticed that the variable names' hex blurbs were different for db
and dbx.  Without going into detail, the UEFI specification defines exactly
which 16-byte Globally Unique IDentifier (GUID) to use for which variable.
Think of GUIDs as a way to ensure there won't be any accidental naming
collisions.

## EFI signature list

So what exactly is stored in PK, KEK, db, and dbx?  I'm glad you asked.

Each of these variables store *EFI signature lists* (ESL).  If you ever
encountered a `.esl` file, this is exactly the kind of bytes that are stored in
PK, KEK, db, and dbx.

The UEFI specification defines [EFI signature lists][] as follows:

    #pragma pack(1)
    typedef struct _EFI_SIGNATURE_DATA {
      EFI_GUID                 SignatureOwner;
      UINT8                    SignatureData [_];
    }   EFI_SIGNATURE_DATA;
    
    typedef struct _EFI_SIGNATURE_LIST {
      EFI_GUID                 SignatureType;
      UINT32                   SignatureListSize;
      UINT32                   SignatureHeaderSize;
      UINT32                   SignatureSize;
    //   UINT8                 SignatureHeader [SignatureHeaderSize];
    //   EFI_SIGNATURE_DATA    Signatures [__][SignatureSize];
    }   EFI_SIGNATURE_LIST;
    #pragma pack()

Maybe a bit clunky to read so let me break it down for you.

`SignatureType`: what type of list is this?  The GUID for a list of SHA256
hashes is `c1c41626-504c-4092-aca9-41f936934328` (`EFI_CERT_SHA256_GUID`).  This
is what you'd use to allowlist or revoke a particular EFI application by hash.
The GUID for a list of DER-encoded X.509 certificates is
`a5c059a1-94e4-4aa7-87b5-ab155c2bf072` (`EFI_CERT_X509_GUID`).  You should see
this GUID matches the earlier hexdump of PK modulo little endian / network byte
order.  For example, `a5c059a1` is in little endian.  Reverse it to get `a1 59
c0 a5`.  To revoke a particular certificate by hash in dbx, you'd use a
different type with GUID `3bd2a492-96c0-4079-b420-fcf98ef103ed`
(`EFI_CERT_X509_SHA256_GUID`).

There are many more types defined but the above should keep you covered.

`SignatureListSize`: byte size of the entire list (including the header).

`SignatureHeaderSize`: size of each individual item in the list.  If you're think
that this sounds impractical for X.509 certificates you're definitely on to
something.

`SignatureHeader`: defined for each `SignatureType`, empty for the above types.

`Signatures`: the per-type specific data which starts with an *owners GUID*
followed by the actual data (such as a DER encoded certificate or a SHA256
hash).  The owner's GUID can be anything and is mainly helpful to label entries.
For example, some tools and UEFI menus might show you previews using this.

If you paid attention you might wonder how to have a list where the X.509
certificates have different sizes, or how to have both certificates and hashes
in a single list.  The answer is: if you have two valid EFI signature lists,
then you can always concatenate them to form a single valid EFI signature list.

    $ cat demo-cert.esl  > list.esl
    $ cat demo-hash.esl >> list.esl

Want to format EFI signatures lists?  Checkout `cert-to-efi-sig-list`,
`cert-to-efi-hash-list`, and `hash-to-efi-sig-list` in the [efitools][] package
on Debian.

[EFI signature lists]: https://uefi.org/specs/UEFI/2.11/32_Secure_Boot_and_Driver_Signing.html#efi-signature-data
[efitools]: https://packages.debian.org/search?keywords=efitools

## Authentication descriptor

As mentioned earlier you can't just write any EFI signature list to PK, KEK, db,
and dbx.  UEFI runtime services would say nope due to missing valid signatures.

To write any of these variables, the data being written is expected to start
with an authentication descriptor.  This is just a fancy way of saying *prepend
a signature to the EFI signature list*.  This signature happens to be an
[authentication_v2 descriptor][] as defined by the UEFI specification, which in
turn references use of PKCS#7.  If this is your jam, knock your self out by
reading the specification and possibly looking at some tools implementing it.

For the rest of you, what's important to know is that this signature spans both
the input EFI signature list, the EFI variable name and GUID, as well as a
timestamp.  UEFI runtime services will not apply a signed update to the wrong
variable, and also not apply an update that's older than the previous update.

If you ever encountered a `.auth` file, this is just an authentication
descriptor concatenated with the signed EFI signature list.  If anyone knows
if the newer authentication_v3 descriptor has seen wide deployment I'd be very
interested to hear from you.  Until then I will stick to the authentication_v2
descriptor.

Want to create signed EFI signature lists?  Checkout `sign-efi-sig-list` from
the [efitools][] package on Debian.  I unfortunately haven't found a good tool
that verifies these signatures, but you can always (at your own risk) play with
the Secure Boot EFI variables on your own system by entering setup mode.  If you
don't know the possible implications of this you probably shouldn't do it.

[authentication_v2 descriptor]: https://uefi.org/specs/UEFI/2.11/08_Services_Runtime_Services.html#using-the-efi-variable-authentication-2-descriptor

## Final words

You learned that the Secure Boot key hierarchy consists of four variables: PK,
KEK, db, and dbx.  PK sits at the top of the hierarchy and stores a single X.509
certificate.  KEK is an intermediate part of the hierarchy and stores one or
more X.509 certificates used to sign-off db and dbx updates.  What Secure Boot
consults when when validating an image is db (trusted X.509 certificates /
SHA256 hashes).  In addition to getting a thumbs up via db, neither the image
nor the X.509 certificate must be revoked by hash in dbx.  Only RSA keys are
supported.

You also got an intuition for the exact format that PK, KEK, db, and dbx use:
EFI signature lists.  You can concatenate multiple EFI signature lists into a
single larger EFI signature list, e.g., using `cat` for two `.esl` files.  For
UEFI runtime services to update PK, KEK, db, or dbx, the new EFI signature list
needs to be signed.  This is done using an authentication descriptor that binds
the signature to the respective variables, data, and timestamps (to avoid
replays).  This authentication descriptor is concatenated with its data to form
a `.auth` file.  The bytes stored in this file can be shipped off to UEFI
runtime services to request variable updates.  Only the data is written on
success.  In other words, you will find EFI signature lists but not
authentication headers in PK, KEK, db, and dbx.

Want to try the mentioned [efitools][] with a bit more hand holding?  I recently
documented a few HOW-TO guides for the System Transparency project
[here](https://git.glasklar.is/system-transparency/project/docs/-/tree/main/content/docs/how-to/secure-boot).