Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions Buildroot/board/FOG/FOS/rootfs_overlay/bin/fog.enrollsbforce
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,10 @@ fi
# has already enrolled this same PK/KEK once. So it always attempts the write
# and reports the firmware state alongside the result, with no MOK fallback:
# muddying a forced-write result with a fallback path would defeat the point
# of the test. sbEnrollDb() itself is unchanged and still fails closed (aborts
# on the first rejected write, per ADR-0003), so a state/key mismatch here just
# returns 1 with nothing changed on disk -- not a partial or unsafe write.
# of the test. sbEnrollDb() still fails closed: a rejected db or KEK write
# aborts before PK (ADR-0003), and PK counts as written only when it reads back
# as FOG's own. So a state/key mismatch here returns non-zero with nothing
# changed on disk -- not a partial or unsafe write.
echo " * [TEST] Firmware state is '$state' -- attempting the direct database"
echo " write anyway (Setup Mode check disabled for this test task)."
echo
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -428,6 +428,44 @@ sbWriteEfiAuthVar() {
[[ -s $path ]] || return 1
return 0
}
# Echo, as hex, the signature list a signed variable update carries.
#
# A .auth file is a 16-byte EFI_TIME, then a WIN_CERTIFICATE_UEFI_GUID whose
# dwLength (the UINT32 at offset 16) counts the whole certificate, then the
# EFI_SIGNATURE_LIST the firmware stores. So the payload starts at
# 16 + dwLength. Echoes nothing when the file is too short to hold one.
#
# $1 path to the .auth file
sbAuthPayloadHex() {
local authfile="$1"
local len
# UEFI fields are little-endian. Say so, rather than rely on the host.
len=$(od --endian=little -An -tu4 -j16 -N4 "$authfile" 2>/dev/null | tr -d '[:space:]')
[[ $len =~ ^[0-9]+$ ]] || return 1
od -An -tx1 -v -j$((16 + len)) "$authfile" 2>/dev/null | tr -d '[:space:]'
}
# Read the platform's PK back and compare it to the one in the given PK.auth.
#
# This reads PK through GetVariable, so the answer is what the firmware stored,
# not what dd was handed. efivarfs prefixes the 4-byte attribute mask, which is
# skipped. A variable the firmware refused reads as empty or absent.
#
# Returns 0 when PK is exactly the one in PK.auth.
# Returns 1 when PK is absent or empty: the platform is in Setup Mode.
# Returns 2 when PK holds something else, or PK.auth carries no payload.
#
# $1 path to PK.auth
sbPkReadback() {
local authfile="$1"
local path="${sbEfiVarDir}/PK-${sbEfiGlobalGuid}"
local want got
[[ -r $path ]] || return 1
got=$(od -An -tx1 -v -j4 "$path" 2>/dev/null | tr -d '[:space:]')
[[ -n $got ]] || return 1
want=$(sbAuthPayloadHex "$authfile")
[[ -n $want && $got == "$want" ]] && return 0
return 2
}
# Enroll this server's certificate into the platform's Secure Boot databases.
#
# Order is db, then KEK, then PK, and it is not interchangeable. Writing PK is
Expand All @@ -438,11 +476,21 @@ sbWriteEfiAuthVar() {
#
# A failure part-way through is NOT that trap: db and KEK written without a PK
# leaves the platform still in Setup Mode, still booting anything, exactly as it
# was found. So this aborts loudly on the first failure (ADR-0003) rather than
# pressing on to the write that would close the door.
#
# Returns 0 on success, 1 on any failure. The caller reports; this does not
# print, so it stays testable.
# was found. So this aborts loudly on the first db or KEK failure (ADR-0003)
# rather than pressing on to the write that would close the door.
#
# sbEnrollDb confirms the PK write by reading PK back (sbPkReadback), not by
# SetupMode. Some firmware stores the PK and still reports SetupMode=1 until
# the next reset (forums topic 18307: the task said "failed", and the machine
# came back in Custom Mode with FOG's certificate in db). It runs the readback
# even when dd reports an error, because only the firmware's own answer says
# whether the platform left Setup Mode.
#
# Returns 0 on success.
# Returns 1 when no PK was stored: the platform is still in Setup Mode.
# Returns 2 when PK holds something other than FOG's PK after the write: the
# platform may have left Setup Mode, so the caller must not say it did not.
# The caller reports; this does not print, so it stays testable.
sbEnrollDb() {
local var guid authfile
# Fetch all three BEFORE writing any. A download that fails halfway would
Expand All @@ -453,16 +501,13 @@ sbEnrollDb() {
authfile="/tmp/${var}.auth"
sbFetchAuthVar "$var" "$authfile" || return 1
done
for var in db KEK PK; do
for var in db KEK; do
[[ $var == db ]] && guid="$sbEfiSecurityGuid" || guid="$sbEfiGlobalGuid"
sbWriteEfiAuthVar "$var" "$guid" "/tmp/${var}.auth" || return 1
done
# SetupMode flipping 1 -> 0 is the firmware confirming it accepted the PK,
# and it is the only confirmation available from a running OS: SecureBoot
# stays 0 until the next boot, because firmware computes it during POST.
# Checking it here turns "dd wrote some bytes" into "the platform enrolled".
[[ $(sbEfiFlag SetupMode) == 0 ]] || return 1
return 0
# The dd status is deliberately not acted on; see the header.
sbWriteEfiAuthVar PK "$sbEfiGlobalGuid" "/tmp/PK.auth"
sbPkReadback "/tmp/PK.auth"
}
# Add Microsoft's 2023 CAs to db on a machine that is NOT in Setup Mode.
#
Expand Down Expand Up @@ -663,20 +708,40 @@ sbEnroll() {
echo " needed."
echo
dots "Enrolling Secure Boot keys"
if ! sbEnrollDb; then
echo "Failed"
debugPause
# Deliberately spells out the state the machine is left in. A
# partial enrollment stops before the PK write, so the platform is
# still in Setup Mode and still boots exactly what it booted before
# -- that is worth saying, because "Secure Boot enrollment failed"
# otherwise reads like the machine may now be unbootable, and
# someone will make an unnecessary trip to the firmware screen.
"$fail" "Automatic Secure Boot enrollment failed. ($0)\n This machine is still in Setup Mode and still boots as it did before;\n nothing has been made unbootable.\n Check that ${web}service/secureboot/ serves PK.auth, KEK.auth and db.auth --\n the FOG server needs efitools installed to produce them."
return 1
fi
sbEnrollDb
case $? in
0) ;;
1)
echo "Failed"
debugPause
# Deliberately spells out the state the machine is left in.
# rc 1 means PK reads back absent, so the platform is still in
# Setup Mode and still boots exactly what it booted before --
# that is worth saying, because "Secure Boot enrollment failed"
# otherwise reads like the machine may now be unbootable, and
# someone will make an unnecessary trip to the firmware screen.
"$fail" "Automatic Secure Boot enrollment failed. ($0)\n This machine is still in Setup Mode and still boots as it did before;\n nothing has been made unbootable.\n Check that ${web}service/secureboot/ serves PK.auth, KEK.auth and db.auth --\n the FOG server needs efitools installed to produce them."
return 1
;;
*)
echo "Failed"
debugPause
# rc 2: a PK is present, and it is not this server's. The
# platform may have left Setup Mode, so the message must not
# say otherwise.
"$fail" "Automatic Secure Boot enrollment could not be confirmed. ($0)\n After the write, the platform key is not the one this FOG server publishes.\n This machine may no longer be in Setup Mode.\n Check the Secure Boot key pages in the firmware setup before you turn\n Secure Boot enforcement on."
return 1
;;
esac
echo "Done"
debugPause
# Some firmware stores the PK but reports SetupMode=1 until the next
# reset (forums topic 18307). This note makes the next report of it
# explain itself.
if [[ $(sbEfiFlag SetupMode) == 1 ]]; then
echo " * The firmware still reports Setup Mode. It stored FOG's platform key,"
echo " so this is expected on firmware that updates that flag at the next reboot."
fi

echo
echo "=============================================================================="
Expand Down
28 changes: 21 additions & 7 deletions docs/adr/0009-secure-boot-enrolment-paths.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,13 +262,27 @@ a success that enrolled nothing.

The Setup Mode path has the same shape of guard, because `dd` can write bytes
into efivarfs that the firmware then declines to apply. `sbEnrollDb()` therefore
re-reads `SetupMode` and requires it to have flipped `1 → 0` before reporting
success: that is the firmware confirming it accepted the `PK`, and it is the only
confirmation available before a reboot (`SecureBoot` stays `0` until the next
POST computes it). An enrollment that failed part-way stops before the `PK` write,
so the machine is still in Setup Mode and still boots whatever it booted before —
`sbEnroll()` says so explicitly, because "Secure Boot enrollment failed"
otherwise reads like the machine may now be unbootable.
reads `PK` back through GetVariable and requires it to equal the signature list
inside `PK.auth` before it reports success. That is the firmware's own answer to
"did you store the PK", so it runs even when `dd` reports an error.

This check used to be `SetupMode` flipping `1 → 0`. Some firmware stores the PK
and still reports `SetupMode=1` until the next reset. On that firmware the task
said "failed" on an enrolled machine (forums topic 18307). `SecureBoot` is no
help either, because it stays `0` until the next POST computes it. The task now
prints a note when `SetupMode` still reads `1` after a confirmed PK.

The result has three outcomes, and each gets its own message:

| `PK` after the write | Platform state | `sbEnroll()` says |
|---|---|---|
| FOG's PK | enrolled | success |
| absent | still in Setup Mode, boots as before | "enrollment failed … still in Setup Mode" |
| some other PK | may have left Setup Mode | "could not be confirmed … check the firmware key pages" |

A failure at `db` or `KEK` stops before the `PK` write, so the machine is still
in Setup Mode. `sbEnroll()` says so explicitly, because "Secure Boot enrollment
failed" otherwise reads like the machine may now be unbootable.

## Enrolling at registration (fogproject#1860)

Expand Down
Binary file added tests/checks/fixtures/secureboot/PK.auth
Binary file not shown.
Binary file added tests/checks/fixtures/secureboot/PK.esl
Binary file not shown.
116 changes: 94 additions & 22 deletions tests/checks/secureboot.sh
Original file line number Diff line number Diff line change
Expand Up @@ -132,13 +132,16 @@ if [[ $url == *.auth ]]; then
head -c 64 /dev/zero > "$dest"
exit 0
fi
# 16-byte EFI_TIME, dwLength, wRevision=0x0200, wCertificateType=0x0EF1,
# then filler standing in for the GUID and PKCS#7 blob. Only the four bytes
# at offset 20 are load-bearing for the validator under test.
# The real layout, at fixture scale: a 16-byte EFI_TIME, then a
# WIN_CERTIFICATE_UEFI_GUID whose dwLength (0x18 = 24) covers its 8-byte
# header and a 16-byte block standing in for the CertType GUID and PKCS#7
# blob, then the EFI_SIGNATURE_LIST the firmware stores. The validator reads
# offset 20; sbPkReadback reads the list at 16 + dwLength.
{
printf '\xea\x07\x08\x03\x0c\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
printf '\x30\x00\x00\x00\x00\x02\xf1\x0e'
printf 'AUTHBODY-%s-PADDINGPADDINGPADDING' "$name"
printf '\x18\x00\x00\x00\x00\x02\xf1\x0e'
printf '%-16.16s' "AUTHBODY-$name"
printf 'ESL-%s-SIGNATURELIST' "$name"
} > "$dest"
exit 0
fi
Expand All @@ -159,9 +162,9 @@ echo "chattr $*" >> "$SANDBOX/calls"
exit 0
EOF

# dd double: logs argv, then hands off to the real dd so the variable file ends
# up with the bytes actually written. $FAKE_DD_FAIL names one variable whose
# write should fail, so an abort mid-sequence can be tested.
# dd double: logs argv, then models the firmware storing the write. $FAKE_DD_FAIL
# names one variable whose write should fail and store nothing, so an abort
# mid-sequence can be tested.
cat > "$STUBBIN/dd" <<'EOF'
#!/bin/bash
echo "dd $*" >> "$SANDBOX/calls"
Expand Down Expand Up @@ -189,14 +192,40 @@ if [[ $(od -An -tx1 -N1 "$in" | tr -d '[:space:]') == 67 ]]; then
tail -c +5 "$in" >> "$out" || exit 1
exit 0
fi
/usr/bin/dd "$@" || exit 1
# Writing a PK is what takes a platform out of Setup Mode. Modelling that here
# is the only way to test that sbEnrollDb confirms the enrollment from the
# firmware rather than from dd's exit status.
if [[ ${out##*/} == PK-* && -z $FAKE_PK_KEEPS_SETUP ]]; then
# Authenticated write (0x27). The real dd runs with the same arguments into
# $SANDBOX/handed-<var>, which keeps what the kernel was handed for cases 34-35.
# The variable then holds what firmware keeps: the attribute word plus the
# EFI_SIGNATURE_LIST after the 16 + dwLength descriptor, never the descriptor.
# A GetVariable readback (sbPkReadback) sees exactly that.
name="${out##*/}"; name="${name%%-*}"
handed="$SANDBOX/handed-$name"
args=()
for a in "$@"; do
[[ $a == of=* ]] && a="of=$handed"
args+=("$a")
done
/usr/bin/dd "${args[@]}" || exit 1
# $FAKE_PK_DECLINED: dd succeeds, firmware keeps nothing.
[[ $name == PK && -n $FAKE_PK_DECLINED ]] && exit 0
len=$(od -An -tu4 -j20 -N4 "$handed" | tr -d '[:space:]')
{
head -c 4 "$handed"
if [[ $name == PK && -n $FAKE_PK_FOREIGN ]]; then
printf 'ESL-SOMEONE-ELSES-PK'
else
tail -c +$((4 + 16 + len + 1)) "$handed"
fi
} > "$out"
# Writing a PK is what takes a platform out of Setup Mode. $FAKE_PK_KEEPS_SETUP
# models firmware that stores the PK but reports SetupMode=1 until the next
# reset (forums topic 18307).
if [[ $name == PK && -z $FAKE_PK_KEEPS_SETUP ]]; then
guid="8be4df61-93ca-11d2-aa0d-00e098032b8c"
printf '\x07\x00\x00\x00\x00' > "${out%/*}/SetupMode-$guid"
fi
# $FAKE_DD_ERR_AFTER_STORE names a variable the firmware stores while the
# write still reports an error.
[[ -n $FAKE_DD_ERR_AFTER_STORE && $name == "$FAKE_DD_ERR_AFTER_STORE" ]] && exit 1
exit 0
EOF

Expand Down Expand Up @@ -304,13 +333,14 @@ new_case() {
FAKE_CURL_BODY="der"; FAKE_MOUNT_FAIL=""; FAKE_UNMOUNTED=""
FAKE_AUTH_FAIL=""; FAKE_DD_FAIL=""; FAKE_PK_KEEPS_SETUP=""
FAKE_AUTH_GARBAGE=""; FAKE_APPEND_IGNORED=""
export FAKE_APPEND_IGNORED
FAKE_PK_DECLINED=""; FAKE_PK_FOREIGN=""; FAKE_DD_ERR_AFTER_STORE=""
export FAKE_APPEND_IGNORED FAKE_PK_DECLINED FAKE_PK_FOREIGN FAKE_DD_ERR_AFTER_STORE
export FAKE_GENHASH_FAIL FAKE_GENHASH_GARBAGE FAKE_IMPORT_FAIL \
FAKE_IMPORT_NOOP FAKE_KEY_ENROLLED FAKE_KEY_IN_DB FAKE_CURL_BODY \
FAKE_MOUNT_FAIL FAKE_UNMOUNTED FAKE_AUTH_FAIL FAKE_DD_FAIL \
FAKE_PK_KEEPS_SETUP FAKE_AUTH_GARBAGE
rm -f "$SANDBOX/calls" "$SANDBOX/staged" "$SANDBOX/.mokpwhash" >/dev/null 2>&1
rm -f "$SANDBOX"/*.auth "$SANDBOX"/.sbauth.* >/dev/null 2>&1
rm -f "$SANDBOX"/*.auth "$SANDBOX"/.sbauth.* "$SANDBOX"/handed-* >/dev/null 2>&1
: > "$SANDBOX/calls"
}

Expand Down Expand Up @@ -651,7 +681,7 @@ check "33. attribute prefix is 0x27 little-endian" \
# or padded it would produce a signature the firmware rejects.
new_case; make_firmware 1 0
lib 'sbEnrollDb' >/dev/null 2>&1
if od -An -c "$EFIVARS/db-$SECURITY_GUID" 2>/dev/null | tr -d ' \n' | grep -q 'AUTHBODY-db'; then
if od -An -c "$SANDBOX/handed-db" 2>/dev/null | tr -d ' \n' | grep -q 'AUTHBODY-db'; then
echo "PASS: 34. the .auth payload is written verbatim after the prefix"
PASS=$((PASS + 1))
else
Expand Down Expand Up @@ -713,18 +743,60 @@ else
fi

# 39. THE silent-failure guard for this path, mirroring case 23. dd can write
# bytes into efivarfs that the firmware then declines to apply. SetupMode
# flipping 1 -> 0 is the firmware confirming it took the PK, and it is the only
# confirmation available before a reboot.
new_case; make_firmware 1 0; FAKE_PK_KEEPS_SETUP=1; export FAKE_PK_KEEPS_SETUP
check "39. writes succeed but SetupMode stays 1 -> refuse" \
"$(lib 'sbEnrollDb && echo ok || echo refused')" "refused"
# bytes into efivarfs that the firmware then declines to apply. The PK read
# back through GetVariable is the firmware's answer. SetupMode is not: some
# firmware stores the PK and reports SetupMode=1 until the next reset, and the
# task then said "failed" on an enrolled machine (forums topic 18307).
new_case; make_firmware 1 0; FAKE_PK_KEEPS_SETUP=1
check "39. PK stored, SetupMode still reads 1 -> success" \
"$(lib 'sbEnrollDb; echo "rc=$?"')" "rc=0"
new_case; make_firmware 1 0; FAKE_PK_KEEPS_SETUP=1
check "39a. ... and the task says why SetupMode still reads 1" \
"$(lib 'sbEnroll handleError' | grep -c 'still reports Setup Mode')" "1"

new_case; make_firmware 1 0; FAKE_PK_DECLINED=1
check "39b. dd succeeds, firmware keeps no PK -> rc 1 (still Setup Mode)" \
"$(lib 'sbEnrollDb; echo "rc=$?"')" "rc=1"

new_case; make_firmware 1 0; FAKE_DD_FAIL=PK
check "39c. PK write fails and stores nothing -> rc 1" \
"$(lib 'sbEnrollDb; echo "rc=$?"')" "rc=1"

new_case; make_firmware 1 0; FAKE_DD_ERR_AFTER_STORE=PK
check "39d. PK stored but dd reports an error -> success" \
"$(lib 'sbEnrollDb; echo "rc=$?"')" "rc=0"

new_case; make_firmware 1 0; FAKE_PK_FOREIGN=1
check "39e. a PK that is not FOG's after the write -> rc 2" \
"$(lib 'sbEnrollDb; echo "rc=$?"')" "rc=2"
new_case; make_firmware 1 0; FAKE_PK_FOREIGN=1
GOT="$(lib 'sbEnroll handleError')"
check "39f. ... and the task reports it as unconfirmed" \
"$(grep -c '^HANDLEERROR: Automatic Secure Boot enrollment could not be confirmed' <<<"$GOT")" "1"
check "39f2. ... without claiming Setup Mode" \
"$(grep -c 'still in Setup Mode' <<<"$GOT")" "0"

new_case; make_firmware 1 0; FAKE_PK_DECLINED=1
check "39g. no PK stored -> the task says it is still in Setup Mode" \
"$(lib 'sbEnroll handleError' | grep -c 'still in Setup Mode')" "1"

# 40. Happy path: all three written, firmware left Setup Mode.
new_case; make_firmware 1 0
check "40. enrollment succeeds when the firmware leaves Setup Mode" \
"$(lib 'sbEnrollDb && echo ok || echo refused')" "ok"

# 40b-40c. The fixtures above share the parser's own reading of dwLength, so
# they cannot catch a wrong one. fixtures/secureboot/ holds a REAL PK.auth from
# efitools' sign-efi-sig-list (throwaway key, not kept) and the PK.esl it
# signed, from cert-to-efi-sig-list. The payload must be exactly that list.
FIXDIR="$HERE/fixtures/secureboot"
new_case; make_firmware 1 0
check "40b. a real PK.auth: the payload is exactly the signed EFI_SIGNATURE_LIST" \
"$(lib "sbAuthPayloadHex '$FIXDIR/PK.auth'")" "$(od -An -tx1 -v "$FIXDIR/PK.esl" | tr -d '[:space:]')"
{ printf '\x27\x00\x00\x00'; cat "$FIXDIR/PK.esl"; } > "$EFIVARS/PK-$GLOBAL_GUID"
check "40c. a real PK.auth matches the PK the firmware stored from it" \
"$(lib "sbPkReadback '$FIXDIR/PK.auth'; echo rc=\$?")" "rc=0"

# --- the Microsoft 2023 CA update (User Mode, append) ---

# Build a db or KEK holding several certificates, one signature list each.
Expand Down
Loading