Lets a deployment gate the TPM firmware-update start command behind its own
platform hierarchy policy instead of the vendor default. Previously wolfTPM
always managed that authorization internally: on Infineon it installed and
satisfied a PolicyCommandCode(TPM_CC_FieldUpgradeStartVendor) policy on the
platform primary policy, and on ST33 it used password authorization with an
empty platform password. Both assume default platform auth, which a hardened
deployment will not have.
New _ex entry points take an already-satisfied session:
wolfTPM2_FirmwareUpgradeHash_ex()
wolfTPM2_FirmwareUpgrade_ex()
wolfTPM2_FirmwareUpgradeRecover_ex()
Passing NULL for startSession keeps the existing library-managed behavior, so
the original functions are unchanged wrappers and existing code is unaffected.
With a session supplied, Infineon no longer overwrites the platform primary
policy (the caller provisions it) and ST33 uses the session in place of
TPM_RS_PW.
Supporting wrappers:
wolfTPM2_PolicyOR() satisfy a session with a compound OR
wolfTPM2_PolicyCommandCodeMake() offline PolicyCommandCode digest
wolfTPM2_IsAlgSupported() report whether the TPM implements an alg
PolicyOR is hash-agnostic (each branch carries its own size), so SHA2-256
through SHA2-512 policy branches all work. It requires at least two branches
per TPM 2.0 Part 3 Sec.23.6 and validates each branch size against the digest
buffer. PolicyCommandCodeMake takes digestSz as in/out - input is the output
buffer capacity and BUFFER_E is returned when it is too small, checked before
the buffer is written. IsAlgSupported reports through an out-parameter and
returns TPM_RC, so a capability-query failure cannot be misread as
"supported"; it sets the out-parameter to 0 on every error path.
Session contract: the vendor FieldUpgradeStart commands are hand-marshalled
with an authorization area carrying only the session handle - empty
nonceCaller, zero attributes, empty HMAC. That is correct only for an
unsalted, unbound policy session with no auth value, so the _ex path validates
the caller session up front and rejects anything needing a computed session
HMAC or parameter encryption (PolicyAuthValue/PolicyPassword, attached auth
value, bind, salt, encrypt/decrypt/audit attributes, or a non-policy handle).
Validation runs before any TPM traffic. On a successful start the TPM consumes
the session and the library sets handle.hndl to TPM_RH_NULL; this is now
documented, including that it is not zero and that wolfTPM2_UnloadHandle
no-ops on it.
Examples: ifx_fw_update and st33_fw_update gain --policy, --policyor and
--policytest, backed by a shared examples/firmware/firmware_policy.c. The
--policytest mode is a non-destructive self-test that checks the TPM's running
policy digest against an offline computation at SHA2-256/384/512, skipping any
hash the TPM does not implement or the local wolfCrypt build was not compiled
with (a build mismatch is a skip, not a failure). The provisioned PolicyOR
carries a PolicyCommandCode(TPM_CC_SetPrimaryPolicy) branch so the policy can
authorize its own removal, and cleanup is gated on a FirmwarePolicyCtx that
records what was actually provisioned, so an early failure cannot clear a
policy the deployment installed itself. A failed rollback is reported but
never overwrites the upgrade error that explains the run, and is skipped once
the start has succeeded (the TPM has reset into upgrade mode and will not
service SetPrimaryPolicy).
Because TPM 2.0 offers no way to read a hierarchy authPolicy back, the example
cannot detect or restore one it replaces, so provisioning prints an explicit
warning naming that. The policy modes are also refused where the session could
never be used: any Infineon operational mode other than normal (recovery and
finalize skip the start entirely), and on ST33 when the TPM is already in
firmware-upgrade mode - previously the flags were silently ignored there,
which is the authorization downgrade they exist to prevent. Rollback normally uses platform password
authorization, which an installed authPolicy does not disable (TPM 2.0 Part 1
Sec.19.7); this was confirmed on ST33KTPM2X, SLB9670 and SLB9673 parts.
The firmware examples now require wolfCrypt in their feature guards. They
drive wolfTPM2_FirmwareUpgrade_ex, which hashes the manifest with SHA-384 and
only exists with wolfCrypt, so --enable-firmware with --disable-wolfcrypt
previously failed to compile.
Also converts examples/nvram/extend.c to the new PolicyCommandCodeMake
capacity contract.
Tests: argument validation and known-answer vectors for the new wrappers,
short-buffer and canary coverage for PolicyCommandCodeMake, caller-session
rejection for every unsupported session shape plus an accepted session,
simulator-backed success paths for PolicyOR and IsAlgSupported, and a
regression test that a platform authPolicy remains clearable with password
authorization while a non-matching policy session is refused.
David Garske
Aidan Garske
Aidan Garske
Eric Blankenhorn