Add optional mTLS support to the tang pin

[liyue32]

Summary

Adds optional mutual-TLS (mTLS) support to the Tang pin, allowing Clevis to authenticate to a Tang server (typically fronted by a TLS-terminating reverse proxy) with a client certificate, and to verify the server certificate against a custom CA.
The feature is fully opt-in: when none of the new properties are set, the pin behaves exactly as before (plain HTTP/HTTPS with the system's default CA trust). Existing JWEs and workflows are unaffected.

Motivation

Adding mTLS lets the Tang server (typically via a TLS-terminating reverse proxy) authenticate the client's identity through its client certificate. This unlocks per-machine access control on top of the existing network-binding model. In particular, single-machine revocation: revoking or refusing a specific client certificate immediately prevents that one machine from recovering its keys, without affecting any other machine or requiring key rotation on the server. This matches how we want to adopt Clevis out of the box at Meta: bind machines to Tang for automated unlock, and retain the ability to revoke an individual host's recovery access by its identity. It's also useful more generally for any deployment where the Tang server is fronted by HTTPS with client-certificate authentication, or uses a server certificate signed by a private/internal CA.

What changed

Three new optional config properties are accepted by clevis encrypt tang:

1. cacert: curl --cacert
2. cert: curl --cert
3. key: curl --key

When any of above are set:

1. passed to curl when fetching the advertisement during encryption, and
2. persisted into the JWE protected header under clevis.tang, so that clevis decrypt reuses them for the POST /rec request without any additional configuration (Clevis decryption takes no config by design, so this metadata must travel in the JWE).

Example:

  clevis encrypt tang '{
    "url":"https://tang.example.com",
    "cacert":"/etc/clevis/ca.crt",
    "cert":"/etc/clevis/client.crt",
    "key":"/etc/clevis/client.key"
  }' < PT > JWE

Backward compatibility

• When no mTLS properties are set, the injected curl option array is empty, so curl is invoked identically to before.
• Existing JWEs have no mTLS header fields; decryption reads them as absent and takes the unchanged code path.

Tests

• Adds a new pin-tang-mtls integration test plus tang_generate_certs, tang_run_mtls, and tang_mtls_sanity_check helpers. The harness fronts tangd with a TLS listener (socat OPENSSL-LISTEN) that mandates client-certificate verification. The test covers:
  • Positive: encrypt (GET /adv) + decrypt (POST /rec) round-trip succeed over mTLS. Since the server enforces client-cert verification, success proves the pin actually presents the client certificate.
  • Header round-trip: the cacert/cert/key paths are correctly persisted into and read back from the JWE protected header.
  • Negative: without a client certificate, encryption fails — proving mTLS is enforced, not silently downgraded.

[sarroutbi]

/packit test

[liyue32]

@sarroutbi I could not see the detailed error message of centos-stream-10-x86_64:pkcs11 failure, but seems like it is timeout issue, could you help to take a look if this is related with my PR changes?

[sergio-correia]

/packit retest-failed

[sergio-correia]

The on_exit trap is registered (line 29) before tang_mtls_sanity_check (line 32), which runs before TMP is assigned (line 34). If the sanity check calls skip_test, the trap fires with TMP unset, and tang_stop "" ends up calling error "tang_stop: please specify 'basedir'" which exits 1. That converts a SKIP (exit 77) into a FAIL (exit 1).

This will break CI on systems that have socat+tangd but socat was built without OpenSSL support.

Compare with pin-tang, where TMP="$(mktemp -d)" is set right after the trap with no skip-able call in between.

Please guard the cleanup so it tolerates an unset TMP:

Suggested change

	on_exit() {
	exit_status=$?
	tang_stop "${TMP}"
	[ -d "$TMP" ] && rm -rf "$TMP"
	exit "${exit_status}"
	}
	on_exit() {
	exit_status=$?
	[ -n "${TMP}" ] && tang_stop "${TMP}"
	[ -d "${TMP}" ] && rm -rf "$TMP"
	exit "${exit_status}"
	}

[sergio-correia]

These paths are never validated for existence before use. The existing adv file path is checked (line 105: if ! [ -f "$jws" ]), so there is a consistency gap.

If a user typos a path (e.g., clietn.crt), two things can happen:

1. When the advertisement is fetched via curl, curl -sfg fails silently and the user sees "Unable to fetch advertisement", which points them at network/DNS issues instead of the real problem.

2. When adv is provided inline, curl is never called, encryption succeeds, and the bad path gets permanently baked into the JWE header. Every decrypt attempt then fails at boot with "Error communicating with server".

Please add file-existence checks after extracting the paths, matching the adv validation pattern:

[ -n "$cacert" ] && [ ! -f "$cacert" ] && { echo "CA cert file '$cacert' not found!" >&2; exit 1; }
[ -n "$cert" ]   && [ ! -f "$cert" ]   && { echo "Client cert file '$cert' not found!" >&2; exit 1; }
[ -n "$key" ]    && [ ! -f "$key" ]    && { echo "Client key file '$key' not found!" >&2; exit 1; }

[sergio-correia]

During decryption, cacert, cert, key (and url) are all extracted from the JWE protected header and fed to curl (line 115) before the AEAD integrity check at line 128 (jose jwe dec). The url field was already consumed unauthenticated before this patch, so this is a pre-existing design property of clevis-tang. However, cacert qualitatively extends the attack surface: an attacker who can modify the stored JWE can now also override which CA curl trusts, enabling MITM against the legitimate tang server with a self-signed cert planted on disk. Previously, modifying url alone still required a certificate trusted by the system CA store.

The practical exploitability is limited (requires disk write access + network position, and the ECMR exchange value alone does not reveal the decryption key), so this may be acceptable as a known trade-off.

Worth considering: validate that cert/key/cacert paths are under an expected prefix (e.g., /etc/clevis/), or use indirection (store a profile name, resolve to paths at runtime from a fixed directory). At minimum, document the trust model explicitly so users understand the implication.

[sergio-correia]

When mTLS parameters are present in the JWE header but the referenced files no longer exist (cert rotation, initramfs rebuilt without them), curl -sfg fails silently and all the user sees is this generic message. In the initramfs at boot, this sends the operator chasing network/firewall issues when the real problem is a missing certificate file.

The man page already warns about ensuring files are in the initramfs, which tells us this is a known footgun. Would it make sense to check the files exist before the curl call and produce a targeted diagnostic?

[ -n "$cacert" ] && [ ! -f "$cacert" ] && { echo "mTLS CA cert '$cacert' not found (is it in the initramfs?)" >&2; exit 1; }
[ -n "$cert" ]   && [ ! -f "$cert" ]   && { echo "mTLS client cert '$cert' not found (is it in the initramfs?)" >&2; exit 1; }
[ -n "$key" ]    && [ ! -f "$key" ]    && { echo "mTLS client key '$key' not found (is it in the initramfs?)" >&2; exit 1; }

[sergio-correia]

Specifying key without cert is a no-op: curl ignores --key when --cert is not also provided. If the server requires mTLS, the handshake fails with a generic error and there is no indication that cert was missing. Please add a consistency check:

[ -n "$key" ] && [ -z "$cert" ] && { echo "'key' requires 'cert' to also be set!" >&2; exit 1; }