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
#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
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

```sh
~/> 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:

```sh
~/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):

```sh
# 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"}
```