#!/usr/bin/env bash
# Installed at /usr/local/sbin/tpm-keyring-unseal, root:root mode 0700.
# Invoked only by the pam_tpm_keyring_authtok PAM module (running as root
# during authentication) with the target username as $1. Prints the sealed
# password to stdout on success, nothing on failure. Never invoked directly
# by a user - the PAM module is the only intended caller.
set -euo pipefail

USERNAME="${1:?username required}"
HOME_DIR="$(getent passwd "$USERNAME" | cut -d: -f6)"
[ -n "$HOME_DIR" ] || exit 1

DATA_DIR="$HOME_DIR/.local/share/tpm-keyring-unlock"
PCR_BANK="sha256:7"

[ -f "$DATA_DIR/seal.priv" ] || exit 1

# This script runs as root and reaches $DATA_DIR purely by resolving $HOME
# out of getent - it has no other evidence that what it is about to unseal
# belongs to the user being authenticated. It has to check, because nothing
# else does: the sealed blob has no auth value and a PCR7-only policy, so it
# carries no notion of whose it is. Without this, one user could point their
# own data dir at another's (a symlink is enough; the path is entirely theirs
# to shape) and have root unseal the *other* user's keyring password into
# their login. See JOURNAL.md, 2026-09-15.
#
# Ownership of the resolved files, not "is this a symlink": a home directory
# legitimately living behind a symlink is somebody's real setup, and the
# thing that actually matters is who owns what we end up reading. Owned by
# the target user and not writable by group or other - a group-writable data
# dir would let somebody else swap the blob under root's nose.
TARGET_UID="$(getent passwd "$USERNAME" | cut -d: -f3)"
[ -n "$TARGET_UID" ] || exit 1

# Open the blobs ONCE, right here, and never name those paths again. This is
# the whole reason the check below is trustworthy, and it is not a style
# preference - checking a path and then reading the same path later is two
# separate resolutions with a window in between, and everything in that
# window belongs to the user we are checking up on. They own every component
# of $DATA_DIR, so they can swap it for a symlink to somebody else's data dir
# after the check has passed and before the read happens. The window here is
# not a few instructions either: the flock below routinely waits, because GDM
# runs gdm-fingerprint and gdm-password as parallel PAM conversations and
# both land in this script.
#
# A file descriptor is immune to that. Once open it refers to one inode, and
# /proc/self/fd/N is a procfs magic link that resolves back to that inode
# rather than re-walking the path - so stat'ing it reports what we actually
# opened, and reading from it returns what we actually opened, whatever the
# path means by then. Confirmed rather than assumed; see JOURNAL.md,
# 2026-09-15.
exec 7<"$DATA_DIR/seal.priv" || exit 1
exec 8<"$DATA_DIR/seal.pub" || exit 1

# Now the ownership question, asked of the descriptors instead of the paths.
# This script runs as root and reached $DATA_DIR purely by resolving $HOME
# out of getent - it has no other evidence that what it is about to unseal
# belongs to the user being authenticated, and nothing else supplies any: the
# sealed blob has no auth value and a PCR7-only policy, so it carries no
# notion of whose it is.
for fd in 7 8; do
  owner="$(stat -Lc '%u' "/proc/self/fd/$fd" 2>/dev/null || true)"
  mode="$(stat -Lc '%a' "/proc/self/fd/$fd" 2>/dev/null || true)"
  size="$(stat -Lc '%s' "/proc/self/fd/$fd" 2>/dev/null || true)"
  # Sealed blobs are tiny - tpm2_create writes ~80 bytes of public area and
  # ~140 of private. The cap is not about TPM limits, it is about what these
  # descriptors get copied into below: root-owned scratch under /tmp, which
  # is tmpfs, which is RAM. Without a bound, a user could grow their own
  # seal.priv to arbitrary size and make root fill memory on every login
  # attempt. Refused rather than truncated, because a truncated blob would
  # come back as a confusing tpm2 error instead of the real reason.
  if [ -z "$size" ] || [ "$size" -gt 65536 ]; then
    echo "tpm-keyring-unseal: sealed data is implausibly large - refusing." >&2
    exit 1
  fi
  if [ "$owner" != "$TARGET_UID" ]; then
    echo "tpm-keyring-unseal: sealed data is not owned by $USERNAME - refusing." >&2
    exit 1
  fi
  # 022 = group-write | other-write. The leading 0 makes bash read stat's
  # output as octal; a setuid/sticky prefix ("2755") stays harmless here
  # because the mask only looks at those two bits.
  if [ -z "$mode" ] || [ $(( 0$mode & 022 )) -ne 0 ]; then
    echo "tpm-keyring-unseal: sealed data is writable by group or other - refusing." >&2
    exit 1
  fi
done

# The directory is checked by path on purpose and is advisory only. A
# group-writable data dir cannot smuggle in another user's blob - the
# descriptor check above settles ownership, and replacing a file needs the
# replacement to be owned by the target user, which needs root. It is still
# worth refusing, because a data dir anyone can write to is not a state this
# tool should keep operating in.
dir_owner="$(stat -Lc '%u' "$DATA_DIR" 2>/dev/null || true)"
dir_mode="$(stat -Lc '%a' "$DATA_DIR" 2>/dev/null || true)"
if [ "$dir_owner" != "$TARGET_UID" ] \
   || [ -z "$dir_mode" ] || [ $(( 0$dir_mode & 022 )) -ne 0 ]; then
  echo "tpm-keyring-unseal: $DATA_DIR is not a private directory owned by" >&2
  echo "$USERNAME - refusing to unseal." >&2
  exit 1
fi

# GDM spawns parallel PAM conversations on one login screen (e.g.
# gdm-fingerprint and gdm-password at once), and this helper is wired into
# both. Two concurrent tpm2_* sequences against the same TPM have been
# observed to fail with "Esys_Unseal ... PCR have changed since checked" -
# one session's PCR-policy check gets invalidated by the other session's
# concurrent activity on the same device. See JOURNAL.md, 2026-08-14. Serialize
# so only one unseal talks to the TPM at a time; the loser just waits its turn
# instead of racing and failing.
# NOT /run/lock: that directory is world-writable (drwxrwxrwt) on a normal
# system, so any local user could create this file first and simply hold the
# lock, stalling every login for the full flock timeout below and then making
# the unseal fail - an unprivileged denial of keyring auto-unlock, needing no
# symlink and no race. /run itself is root-owned and mode 755, so a directory
# created here can only have been created by root. See JOURNAL.md,
# 2026-09-15.
#
# The lock is taken on the directory itself, opened for reading, not on a file
# written inside it. Under SELinux the directory carries the label of whoever
# created it first after boot: xdm_var_run_t when GDM's PAM stack (domain
# xdm_t) gets there first, plain var_run_t when it was a `sudo` run from a
# terminal - the check README suggests. xdm_t may not write a file in the
# latter, so the old `exec 9>"$LOCK_DIR/unseal.lock"` failed every GDM unseal
# until the next reboot. xdm_t may open and lock the directory under either
# label, and flock(2) works on a directory just as on a file. Measured on
# Fedora 44, enforcing; GitHub issue #23, JOURNAL.md 2026-10-05.
LOCK_DIR=/run/tpm-keyring-unlock
if [ -L "$LOCK_DIR" ] || { [ -e "$LOCK_DIR" ] && [ ! -d "$LOCK_DIR" ]; }; then
  echo "tpm-keyring-unseal: $LOCK_DIR exists and is not a directory - refusing." >&2
  exit 1
fi
mkdir -p "$LOCK_DIR"
chmod 700 "$LOCK_DIR"
exec 9<"$LOCK_DIR"
flock -w 10 9 || exit 1

WORKDIR=$(mktemp -d)
trap 'rm -rf "$WORKDIR"' EXIT

# Drain the descriptors opened before the lock into root-owned scratch space,
# and work from these copies from here on. The paths under $DATA_DIR are
# never touched again, so there is nothing left for the user to swap: what
# gets loaded is exactly the inode whose ownership was checked. Sealed blobs
# only - this is the TPM-encrypted object, the same thing already written
# here as seal.ctx, never the unsealed password.
cat <&7 >"$WORKDIR/seal.priv"
cat <&8 >"$WORKDIR/seal.pub"
exec 7<&- 8<&-

# Every tpm2_* call below goes to the kernel's resource manager, named here
# rather than left to the tools. The PAM module starts this script with an
# empty environment, so without it tpm2-tools pick a TCTI themselves, and
# their first choice is tpm2-abrmd whenever it runs. The check right below
# would then test a device the tools do not use (review of PR #24), and the
# unsealed password would pass through the abrmd daemon on its way here. The
# kernel's own resource manager is what install.sh requires and what the
# SELinux module opens up.
TPM_DEVICE=/dev/tpmrm0
export TPM2TOOLS_TCTI="device:$TPM_DEVICE"

# Whether this process may open the TPM at all - asked before anything below
# can blame the persisted primary for a load that failed for another reason.
# Under SELinux that is the policy's call, not the file mode's: GDM's PAM
# stacks run as xdm_t, which Fedora's policy keeps away from the TPM unless
# selinux/tpm_keyring_unlock.cil is loaded. Every tpm2_* call then fails, and
# the fast path below used to report that as an evicted primary (GitHub issue
# #23). Opening the resource manager and closing it again sends the TPM
# nothing. The context goes in the message because it is the whole diagnosis:
# under GDM this lands in the journal as gdm-session-worker.
if ! TPM_OPEN_ERR="$({ : <>"$TPM_DEVICE"; } 2>&1)"; then
  echo "tpm-keyring-unseal: cannot open $TPM_DEVICE (${TPM_OPEN_ERR##*: }) as" \
    "$(id -Z 2>/dev/null || id -un)." >&2
  if [ -e /sys/fs/selinux/enforce ]; then
    echo "tpm-keyring-unseal: SELinux has to let that domain use the TPM -" \
      "see README.md, 'SELinux'." >&2
  fi
  exit 1
fi

# Fast path: if bin/seal.sh has persisted the primary into the TPM's own NV
# storage (see JOURNAL.md, 2026-08-16), reference that handle directly - no
# recomputation needed. Cuts per-login cost from ~7.4s to well under 1s
# (createprimary alone profiled at ~6.9s on this machine's fTPM, 2026-08-14
# entry). tpm2 primary keys are deterministic (same hierarchy + same
# template = same key every time); a *saved context file* for a transient
# object is tied to the TPM's reset count and becomes unloadable after every
# reboot, which is why the slow path below recreates the primary rather than
# loading a saved primary.ctx - see JOURNAL.md.
#
# The handle is read but never trusted. Two independent reasons, both real:
#
#  1. That persistent object is MACHINE-WIDE, not per-user. bin/seal.sh
#     persists it at one fixed handle shared by every user on the box (the
#     primary is deterministic, so the second user to seal reuses the first
#     user's object). So another user's uninstall.sh evicting it - or a TPM
#     clear, or anything else in the tss group calling tpm2_evictcontrol -
#     leaves this user's primary.handle pointing at an empty handle, with
#     the file itself perfectly intact. Keying the fallback off the file's
#     *absence* (which is what this did until 2026-09-15) never fires in
#     that case: tpm2_load just fails and the keyring silently stops
#     unlocking. See JOURNAL.md, 2026-09-15, and GitHub issue #7.
#  2. The file lives in an unprivileged user's home and this script runs as
#     root during authentication. tpm2_load's -C takes a handle *or a
#     context-file path* (it is spelled --parent-context), so unvalidated
#     file content here is a user steering a root-side open of an arbitrary
#     path. Hence the format check before it is ever passed to a tool.
#
# A failed load is the complete and authoritative test: seal.priv is
# cryptographically bound to its real parent's name, so a wrong or absent
# object at that handle cannot load it, and a foreign object squatting
# there gets ignored rather than used. Deliberately NOT done: verifying the
# handle up front with tpm2_readpublic and comparing names the way
# bin/seal.sh does. The helper has nothing to compare against without first
# deriving a fresh primary - i.e. paying the ~7s createprimary this whole
# fast path exists to avoid - so "verify first" would cost the optimization
# on every login to detect what the load already detects for free.
PRIMARY_HANDLE=""
if [ -f "$DATA_DIR/primary.handle" ]; then
  # `|| true` so an unreadable file (root-squashed NFS home, say) routes to
  # the slow path instead of killing the script under `set -e`. Whitespace
  # is stripped because a stray CR or newline would otherwise be passed to
  # -C verbatim.
  PRIMARY_HANDLE="$(tr -d '[:space:]' <"$DATA_DIR/primary.handle" 2>/dev/null || true)"
  # TPM 2.0 persistent objects live in 0x81000000-0x81ffffff; bin/seal.sh
  # never writes anything else. Anything else is treated as "no handle".
  # Spelled out here rather than sourced from bin/lib.sh's
  # TPM_PERSISTENT_HANDLE_RE on purpose: install.sh copies this script alone
  # to /usr/local/sbin, so the repo (and lib.sh with it) need not exist on
  # the machine at authentication time. Keep the two in step by hand - it is
  # the one place in this project where that duplication is deliberate.
  if ! [[ "$PRIMARY_HANDLE" =~ ^0x81[0-9a-fA-F]{6}$ ]]; then
    echo "tpm-keyring-unseal: $DATA_DIR/primary.handle is not a TPM persistent" >&2
    echo "handle; ignoring it and recreating the primary (slower login). Re-run" >&2
    echo "bin/seal.sh to restore the fast path." >&2
    PRIMARY_HANDLE=""
  fi
fi

# `if ! tpm2_load` rather than `tpm2_load || fallback`, and deliberately not
# wrapped in a function: `set -e` is suppressed for the whole body of a
# function invoked in a condition context, which would silently disarm error
# handling for every command inside it.
LOADED=0
if [ -n "$PRIMARY_HANDLE" ]; then
  if tpm2_load -C "$PRIMARY_HANDLE" \
       -u "$WORKDIR/seal.pub" -r "$WORKDIR/seal.priv" \
       -c "$WORKDIR/seal.ctx" >/dev/null 2>"$WORKDIR/load.err"; then
    LOADED=1
  else
    # stderr, never stdout: stdout is the secret channel, and the PAM module
    # copies it verbatim into PAM_AUTHTOK. The module leaves stderr inherited
    # from the login process, so this lands in the journal, where README's
    # troubleshooting section already sends people (`journalctl -b 0 | grep
    # -i tpm`). Says "tpm" on purpose, so that grep finds it.
    echo "tpm-keyring-unseal: the persisted TPM primary at $PRIMARY_HANDLE did not" >&2
    echo "load - it has been evicted (another user's uninstall.sh, or a TPM clear)." >&2
    echo "Recreating it for this login; this adds ~7s. Re-run bin/seal.sh to restore" >&2
    echo "the fast path." >&2
    sed 's/^/tpm-keyring-unseal: tpm2_load: /' "$WORKDIR/load.err" >&2 || true
    # A failed load can still have created a partial context file; the retry
    # below must not be able to succeed off leftovers.
    rm -f "$WORKDIR/seal.ctx"
  fi
fi

# Slow path, unchanged in behavior from before the persisted primary existed:
# recreate the deterministic primary and load under it. Left fatal under
# `set -e` on purpose - if this fails, there is nothing further to try.
# Exactly one retry, never a loop: tpm2_createprimary is deterministic, so a
# second attempt would recompute the identical key and fail identically,
# while costing another ~7s against the PAM module's 25s alarm (which a
# second attempt would blow - see the budget comment in
# pam/pam_tpm_keyring_authtok.c).
if [ "$LOADED" -eq 0 ]; then
  tpm2_createprimary -C o -c "$WORKDIR/primary.ctx" >/dev/null
  tpm2_load -C "$WORKDIR/primary.ctx" \
    -u "$WORKDIR/seal.pub" -r "$WORKDIR/seal.priv" \
    -c "$WORKDIR/seal.ctx" >/dev/null
fi

# Note for anyone tempted to "self-heal" here: this script must never write
# to $DATA_DIR. It runs as root during authentication against a path an
# unprivileged user fully controls, so rewriting or deleting primary.handle
# would be a root write through a symlink that user can plant. Re-persisting
# the primary would be worse still - an unattended machine-wide TPM write
# during one user's login, which is the exact class of thing issue #7 is
# about. bin/seal.sh, running as the user, is the only writer. The cost of
# not healing is a slow login plus the warning above, and that is the right
# trade. See JOURNAL.md, 2026-09-15.

# The policy-session-check-then-use step (startauthsession -> policypcr ->
# unseal) has been observed to fail with "Esys_Unseal ... PCR have changed
# since checked" even with the flock above held and no other concurrent
# caller of this script - the flock only rules out racing against a *second
# copy of this same script*, not whatever else on this machine's fTPM
# (AMD PSP firmware TPM, session-slot-constrained) can perturb a policy
# session in that window. createprimary/load above (on the pre-persisted-
# primary fallback path; a no-op load off the handle otherwise) are
# deterministic given the same sealed blob, so only the fast, cheap final
# step is retried here - not the whole sequence. See JOURNAL.md, 2026-08-14.
UNSEAL_MAX_ATTEMPTS=5
attempt=1
while :; do
  SESSION_CTX="$WORKDIR/session.$attempt"
  if tpm2_startauthsession -S "$SESSION_CTX" --policy-session >/dev/null \
     && tpm2_policypcr -S "$SESSION_CTX" -l "$PCR_BANK" >/dev/null \
     && tpm2_unseal -c "$WORKDIR/seal.ctx" -p "session:$SESSION_CTX"; then
    tpm2_flushcontext "$SESSION_CTX" >/dev/null 2>&1 || true
    break
  fi
  tpm2_flushcontext "$SESSION_CTX" >/dev/null 2>&1 || true
  if [ "$attempt" -ge "$UNSEAL_MAX_ATTEMPTS" ]; then
    exit 1
  fi
  attempt=$((attempt + 1))
  sleep 0.3
done
