tpm2: Support safely rotating the lockout hierarchy authorization value by chrisccoulson · Pull Request #539 · canonical/secboot

chrisccoulson · 2026-04-22T10:09:05Z

This updates the Connection.EnsureProvisioned API to safely support
rotating the authorization value for the lockout hierarchy, which can be
used during reprovisioning. This is particularly required during a
factory reset, when secrets should be rotated.

The lockout hierarchy is used on successful boots to reset the DA
counter. A single authorization failure makes the lockout hierarchy
unavailable for the preprogrammed recovery time (currently 24 hours).
This makes it challenging to update the value because it's not possible
to atomically update both the value in the TPM and the value stored in
persistent storage.

This PR works around this by using a transient authorization policy that
permits the use of the TPM2_HierarchyChangeAuth command with a signed
assertion (TPM2_PolicySigned), using a key that's derived from the
original authorization value. An authorization policy is used by default
for other uses of the lockout hierarchy as this provides a way to detect
a transient state resulting from a previously interrupted update before
using the incorrect authorization value.

The WithProvisionNewLockoutAuthValue option no longer allows an
authorization value to be specified directly. One is derived
automatically from the supplied random source, with the length
determined by the value of the TPM_PT_CONTEXT_HASH property. A callback
is supplied so that the authorization data can be stored to persistent
storage. This happens several times during an update.

This updates the Connection.EnsureProvisioned API to safely support rotating the authorization value for the lockout hierarchy, which can be used during reprovisioning. This is particularly required during a factory reset, when secrets should be rotated. The lockout hierarchy is used on successful boots to reset the DA counter. A single authorization failure makes the lockout hierarchy unavailable for the preprogrammed recovery time (currently 24 hours). This makes it challenging to update the value because it's not possible to atomically update both the value in the TPM and the value stored in persistent storage. This PR works around this by using a transient authorization policy that permits the use of the TPM2_HierarchyChangeAuth command with a signed assertion (TPM2_PolicySigned), using a key that's derived from the original authorization value. An authorization policy is used by default for other uses of the lockout hierarchy as this provides a way to detect a transient state resulting from a previously interrupted update before using the incorrect authorization value. The WithProvisionNewLockoutAuthValue option no longer allows an authorization value to be specified directly. One is derived automatically from the supplied random source, with the length determined by the value of the TPM_PT_CONTEXT_HASH property. A callback is supplied so that the authorization data can be stored to persistent storage. This happens several times during an update.

valentindavid · 2026-04-23T09:39:14Z

+//
+// This option will also resume a previously interrupted update, as long as the most recent authorization
+// data is supplied to [WithLockoutAuthData].
+func WithProvisionNewLockoutAuthValue(rand io.Reader, syncData func([]byte) error) EnsureProvisionedOption {


Would it make more sense to call it WithProvisionNewLockoutAuthData (Data not Value) so people do not think they should call WithLockoutAuthValue. Or maybe use some types for []byte to make them distinct.

That sounds ok.

pedronis

thank you, did a pass

pedronis · 2026-04-23T07:20:49Z

 		case tpm2.IsTPMWarning(err, tpm2.WarningLockout, command):
 			return ErrTPMLockout
-		case tpm2.IsTPMSessionError(err, tpm2.ErrorPolicyFail, command, 1):
-			return ErrInvalidLockoutAuthPolicy


why was this dropped?

It's impossible to hit this case now because authorizeLockout returns ErrInvalidLockoutAuthPolicy instead.

pedronis · 2026-04-23T08:13:31Z

+		return nil
+	}
+
+	opts := []EnsureProvisionedOption{WithLockoutAuthValue(nil), WithProvisionNewLockoutAuthValue(bytes.NewReader(data.lockoutAuthBytes), syncLockoutAuthData)}


these options is what to try if we didn't have a stored auth data/params yet?

Yes, although perhaps there should be an explicit WithUnconfiguredLockoutAuth option instead.

pedronis · 2026-04-23T10:08:23Z

+	case params.AuthPolicy != nil && session.Handle().Type() == tpm2.HandleTypeHMACSession:
+		// authorization was performed with a HMAC session when we have policy data,
+		// which only happens if the lockout hierarchy has no policy set.
+		return ErrLockoutAuthNotInitialized


tests don't' end up here

Oh, that's weird - lockoutauthSuite.TestResetDictionaryAttackLockAuthPolicyUnset is meant to hit this.

Ah, it was a bug in the test :) a2ef396

pedronis · 2026-04-23T10:14:34Z

+		err = m.tpm.HierarchyChangeAuth(m.tpm.LockoutHandleContext(), m.authParams.NewAuthValue, session, m.tpm.HmacSession().IncludeAttrs(tpm2.AttrCommandEncrypt))
+	default:
+		// We're using HMAC auth
+		err = m.tpm.HierarchyChangeAuth(m.tpm.LockoutHandleContext(), m.authParams.NewAuthValue, session.IncludeAttrs(tpm2.AttrCommandEncrypt))


this case is not reached by tests

It turns out that it's not actually possible to hit this case, so I've removed it.

…hData

…rupted These are merged into a new error: ErrLockoutAuthInvalid. There's no point in having 2 different errors for conditions that require the same resolution (calling EnsureProvisioned again).

chrisccoulson · 2026-04-23T20:52:51Z

Ok, I've pushed some updates:

WithProvisionNewLockoutAuthValue is now WithProvisionNewLockoutAuthData.
There is a new WithUnconfiguredLockoutAuth option to avoid having to use WithLockoutAuthValue(nil) on a fresh install.
Along with this, there is a new ErrLockoutAuthInitialized which will be returned if Connection.EnsureProvisioned is called with the new option if the lockout hierarchy already has an authorization value (as an alternative to just tripping the lockout).
I've merged ErrInvalidLockoutAuthPolicy and ErrLockoutAuthUpdateInterrupted into a new error - ErrLockoutAuthInvalid, as there's no need to distinguish between these 2 cases given that they have the same resolution (need to call Connection.EnsureProvisioned again with the WithProvisionNewLockoutAuthData option).

pedronis

thank you

chrisccoulson force-pushed the tpm2-safe-rotate-lockout-auth-value branch 4 times, most recently from b48db59 to 3c9ab81 Compare April 22, 2026 14:26

chrisccoulson force-pushed the tpm2-safe-rotate-lockout-auth-value branch from 3c9ab81 to cf97c51 Compare April 22, 2026 14:27

chrisccoulson marked this pull request as ready for review April 22, 2026 14:28

chrisccoulson requested review from pedronis April 22, 2026 14:28

pedronis requested a review from valentindavid April 22, 2026 15:38

Fix a build failure

e6e8742

valentindavid reviewed Apr 23, 2026

View reviewed changes

Comment thread tpm2/lockoutauth.go

pedronis reviewed Apr 23, 2026

View reviewed changes

valentindavid reviewed Apr 23, 2026

View reviewed changes

Comment thread tpm2/lockoutauth.go

valentindavid reviewed Apr 23, 2026

View reviewed changes

Comment thread tpm2/lockoutauth.go

chrisccoulson added 6 commits April 23, 2026 18:48

Rename WithProvisionNewLockoutAuthValue to WithProvisionNewLockoutAut…

80fc58b

…hData

tpm2: Add WithUnconfiguredLockoutAuth

c01832d

Fix some test failures

cf4c7f1

tpm2: Merge ErrInvalidLockoutAuthPolicy and ErrLockoutAuthUpdateInter…

cfb6e6c

…rupted These are merged into a new error: ErrLockoutAuthInvalid. There's no point in having 2 different errors for conditions that require the same resolution (calling EnsureProvisioned again).

Fix a unit test bug that reduced coverage

a2ef396

Remove a dead case

a37d93f

chrisccoulson requested a review from valentindavid April 23, 2026 20:52

pedronis approved these changes Apr 24, 2026

View reviewed changes

valentindavid approved these changes Apr 24, 2026

View reviewed changes

chrisccoulson merged commit c00dcff into canonical:master Apr 24, 2026
2 checks passed

Conversation

chrisccoulson commented Apr 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pedronis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chrisccoulson commented Apr 23, 2026

Uh oh!

pedronis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants