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]

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.

[liyue32]

Thanks a lot for your review! In my understanding, if attacker could modify JWE header, they could probably also modify the ca trust store in /etc/pki. If this is correct, cacert does not add more security risk here (correct me if my understanding is wrong). I also thought about adding validation for cert/key/cacert paths, but considering this aims to be used generically, it is hard to add any specific cacert path validation so I feel path-prefix validation felt too restrictive here.
I added one section named "mTLS SECURITY MODEL" in clevis-encrypt-tang.1.adoc to describe the potential risk of cacert and recommende that the CA be installed in the system trust store (with cacert omitted) where possible

[liyue32]

address the comments by

• add cert, key and cacert path validation
• Add security model document of using cacert