Expand the TLS concept page

[bgravenorst]

Summary

The TLS concept page (concepts/tls.md) is around 78 words, which makes it the thinnest page on the site. Expand it into a real explanation of the transport security model, and correct two things on it that are misleading.

Current state

The page states that Web3Signer supports TLS for inbound and outbound HTTP JSON-RPC requests and for communication with HashiCorp Vault, notes that keys and certificates must be in password-protected PKCS #12 keystores, and links to two how-to pages.

Why this is needed

This is transport security for a service that holds signing keys. A reader assessing whether Web3Signer is safe to deploy will look for this page specifically, and 78 words does not answer the questions they arrive with. The page currently describes the mechanism without ever describing the model.

The gap that matters most is the trust model. Web3Signer supports two different ways of deciding which peers to trust, and the page does not mention that a choice exists. Inbound connections can be restricted by a known-clients file listing accepted certificate fingerprints, or opened to any client presenting a certificate signed by a trusted CA, or opened to any client at all. Outbound connections use the same fingerprint-pinning idea through known-servers files. Choosing between fingerprint pinning and CA-based trust has real operational consequences, and nothing in the documentation explains the trade-off.

Connections to cover

Three distinct connections can be secured, and the page should treat them separately, because they are configured in different places:

• Inbound, from the validator client to Web3Signer, configured with the --tls-keystore-file, --tls-keystore-password-file, --tls-known-clients-file, --tls-allow-any-client, and --tls-allow-ca-clients options.
• Outbound, from Web3Signer to a downstream node in execution layer mode, configured with the --downstream-http-tls-enabled, --downstream-http-tls-keystore-file, --downstream-http-tls-keystore-password-file, --downstream-http-tls-known-servers-file, and --downstream-http-tls-ca-auth-enabled options.
• Outbound, from Web3Signer to HashiCorp Vault, configured per key in the key configuration file with tlsEnabled and tlsKnownServersPath.

Please confirm this list against the current release before publishing, and check with a maintainer whether the connection to the slashing protection database can also be secured, and if so how it is configured. That connection is not covered anywhere in the documentation today, and a reader securing everything else will ask about it.

Two corrections may be required here

The page describes inbound TLS as applying to "HTTP JSON-RPC requests." The consensus layer signing API is REST, not JSON-RPC, so as written this reads as though TLS applies only to execution layer traffic. Verify the actual scope and describe it accurately.

The page says you must configure "the server (in this example, Besu)" to accept TLS connections. Besu is an execution client, and this sentence only makes sense for the downstream execution layer case. In the validator signing case the relationship is the other way round, with the validator client connecting to Web3Signer. Separate these rather than presenting one as the general case.

Also worth covering

• Why mutual TLS matters more for a signing service than for a typical HTTP service, given that anything able to reach the signing endpoint can request signatures.
• The keystore and truststore model, including why PKCS [ES-9] Add key signer configuration file content #12 is required.
• Certificate rotation, and what has to be restarted or reloaded when a certificate changes.
• What TLS does not protect against. It secures the connection, and it is not authorization. A client that is trusted at the TLS layer can request any signature the signer can produce.