The daemon HTTPS server (when enabled) uses TLS v1.3 for the client server handshake.

The traditional TLS handshake does not provide us with a way to exchange identity certificates between client and server, since only the server certificate is sent to the client. This leaves the current TLS connection relying on basic authentication headers for passing a client identity to the server.

This patch migrates the HTTPS server over from basic authentication to using mutual TLS. The client (see #715) now has to supply a suitable client identity certificate that will be used for verifying the identity during normal API usage, although this requirement is not enforced for end-points with open access.

In #702 we added a pairing manager, which integrates with the daemon API permissions system to facilitate client server pairing during a carefully controlled pairing window on a dedicated API end-point v1/pairing only.

A followup task will provide an official event binding mechanism (trigger manager) by which the pairing window can be enabled when certain events are configured. For now, this cannot be enabled and therefore pairing is not possible. The the patch below hooking in the pairing window enable for testing purposes.

State of HTTPS (mTLS) after this patch

• When Pebble enables the HTTPS server only mTLS connections will be allowed (basic authorization is no longer available on the HTTPS transport, but can still be used with HTTP)
• The Pebble client package adds (see feat(client): mTLS support [2b/2] #715):
  • The ability to supply the client identity certificate, but this is not yet used by the CLI and therefore Pebble cannot use HTTPS today.
  • The ability to obtain the server identity certificate by making an insecure HTTPS connection. Can be used to implement an SSH-like workflow to implement a CLI warning asking the user to trust the server identity for future connections.
  • The ability to pair with the server by supplying the server identity fingerprint. This workflow requires obtaining the fingerprint by other means, such as DNSSD or via a display on the server side.
• The Pairing Manager provides the EnablePairing method, but this is not yet available, and requires future work to support binding events to actions such as pairing enable.

Testing

The following test procedure can offer a demonstration how this works, but the process requires a small temporary patch to enable pairing:

1. Apply the following patch as a temporary step to enable the pairing on startup.

diff --git a/internals/overlord/pairingstate/manager.go b/internals/overlord/pairingstate/manager.go
index 833b979..c933ef9 100644
--- a/internals/overlord/pairingstate/manager.go
+++ b/internals/overlord/pairingstate/manager.go
@@ -131,6 +131,12 @@ func (m *PairingManager) Stop() {
 	m.stopTimer()
 }
 
+// TESTING HACK: Open the pairing window on startup.
+func (m *PairingManager) StartUp() error {
+	fmt.Printf("Pairing Enabled ...")
+	return m.EnablePairing(60 * time.Second)
+}
+
 // PairMTLS adds a client identity with admin permissions to the identity
 // subsystem. A pairing request always closes the pairing window.
 func (m *PairingManager) PairMTLS(clientCert *x509.Certificate) error {

2. Generate the client private key and certificate

~/> openssl genpkey -algorithm ed25519 -out client-key.pem

~/> openssl req -x509 -new -nodes -key client-key.pem -days 365 -out client-cert.pem -subj "/O=Test/CN=client" -addext "keyUsage=critical,digitalSignature" -addext "extendedKeyUsage=clientAuth" -addext "basicConstraints=critical,CA:FALSE"

3. Build pebble, run:

~/pebble> go build ./cmd/pebble
~/pebble> mkdir layers
~/pebble> echo -e "pairing:\n  mode: multiple" > layers/001-default.yaml
~/pebble> PEBBLE=$(pwd) ./pebble run --create-dirs --https=:8443

4. Test HTTPS (within the first 60 seconds of starting pebble):

# Not yet paired.
~/> curl -X GET --cert ./client-cert.pem --key ./client-key.pem --insecure https://localhost:8443/v1/plan?format=yaml
{"type":"error","status-code":401,"status":"Unauthorized","result":{"message":"access denied","kind":"login-required"}}

# Pair during open pairing window (will close window).
~/> curl -X POST -H "Content-Type: application/json" -d '{"action": "pair"}' --cert ./client-cert.pem --key ./client-key.pem --insecure https://localhost:8443/v1/pairing

{"type":"sync","status-code":200,"status":"OK"}

# Test HTTPS with mTLS enabled.
~/> curl -X GET --cert ./client-cert.pem --key ./client-key.pem --insecure https://localhost:8443/v1/plan?format=yaml

{"type":"sync","status-code":200,"status":"OK","result":"pairing:\n    mode: multiple\n"}