Add Secure Communication design doc

Updates projectcontour#881
Updates projectcontour#862

Signed-off-by: Nick Young <ynick@vmware.com>

design/secure-communication.md

@@ -0,0 +1,94 @@
+# Secure Communication for Contour and Envoy
+
+Status: Draft
+
+This document outlines a design for securing gRPC communication between Contour and Envoy, including all the xDS endpoints.
+
+## Goals
+
+- Achieve secure communication between Contour and Envoy, which will allow a split deployment.
+- Allow use of the SDS service in Contour with authentication.
+
+## Non Goals
+
+- Certificate management, including creation or rotation. These are left as an exercise for the reader at this time.
+
+## Definitions
+
+### mTLS
+
+In this document, we use **mTLS** as shorthand for 'mutual TLS client certificate authentication', without implying a key lifetime. That is, we're just talking about both sides having TLS certs, not implying that we're using the more modern form which implies dynamic, short-lifetime certificates managed by an automated mechanism.
+
+## Background
+
+Currently, the default deployment of Contour includes a Contour and an Envoy container, that connect via the Pod's loopback interface. This uses the pod-level security boundary to provide transport security (no-one can listen in) and authentication (no-one other than Envoy can connect).
+
+In order to be able to split the deployment of Contour and Envoy, we must be able to provide an acceptable level of both transport security and authentication between the different pods.
+
+Currently, if you do split the deployment, Contour will assume that anything that talks to the xDS endpoints is authorized for all information in them. Notably, this includes any certificates used in any endpoint. Antyhing that can speak SDS can connect to contour and ask for all the certificates it knows about via SDS. This design is intended to mitigate this problem.
+
+It's also important to note that the certificates talked about in this document are **only** the certificates used to secure the gRPC channel between Contour and Envoy, not any certificates used to serve TLS out of Envoy. As such, this design is wholly separate to any certificate functionality on either Ingress or IngressRoute.
+
+## High-Level Design
+
+We will add configuration to Contour, both for `contour serve` and `contour bootstrap`, to have Contour and Envoy use a shared CA and a keypair each. This will allow a basic split deployment with minimal changes to the current code, using simple Secret mounts into file locations in both a Contour Deployment and Envoy deployment or DaemonSet.
+
+The generation of the certificates and their placement into Secrets in an operable and maintainable way is not in scope for this change, only a basic illustration in the example deployment YAMLs and Howto. However, see [Future Work](#future-work) for more info.
+
+## Detailed Design - mTLS
+
+In order for mTLS to work, each end must know:
+- The CA that the TLS relationship will descend from.
+- Its certificate
+- Its key
+
+This applies both to Contour and Envoy.
+
+To accomplish this, we will add the following new command line options:
+
+To `contour serve`, covering the Contour side:
+- `--contour-cafile`: the CA Bundle for the mutual TLS relationship
+- `--contour-mtls-cert`: The cert for Contour to use to identify itself. (`serve`)
+- `--contour-mtls-key`: The key for Contour to use for its side of the mTLS pairing. (`serve`)
+
+And to `contour bootstrap`, covering Envoy configuration:
+- `--envoy-cafile`: The CA Bundle for the mutual TLS relationship
+- `--envoy-mtls-cert`: The cert for Envoy to use to identify itself.
+- `--envoy-mtls-key`: The key for Envoy to use to identify itself.
+
+If any one of the three options is passed to either `serve` or `bootstrap`, the other two are required, and we will error out if they are not passed.
+
+We will wire these options into the gRPC server establishment process on the Contour side, and supply them in the bootstrap on the Envoy side. This is where the most significant code changes will be required.
+
+We will update the example deployment manifests for the separate deployment options to use these new options, and provide a basic sample howto on generating a CA keypair and mTLS keypairs using command line tools like openssl.
+
+## Security Considerations
+
+In the current design, these certs require the rolling of the deployment to change, they should be long-lived certs (days, weeks, or months), not short-lived (minutes or hours). The CA Keypair should be very long-lived and very tightly controlled, as Contour/Envoy connection security is only as secure as the CA keypair.
+
+As noted above, this is an initial design to *start* the process of being able to run reasonably secure, authenticated, separate deployments of Contour and Envoy. Some things that we *will* address at a later date, but are out of scope for now:
+
+- Certificate generation (apart from a very simple howto to allow users to see how the feature works)
+- Certificate rotation
+
+Implementing this change will, however, improve the security of the split-deployment scenario.
+
+## Future Work
+
+This work is the first phase of a planned three-phase rollout.
+
+### Phase 1: mTLS
+
+This document - allows a more secure split deployment in a very basic way.
+
+### Phase 2: User Experience
+
+This phase will add additional functionality and/or tools to help with the certificate generation and rolling process. Watch [#1184][1] to track this phase.
+
+### Phase 3: Secure by default
+
+This phase will flip the example deployments to all use a secure mode, make those command line options default, and include an option to restore the current behaviour. Watch [#1185][2] to track this phase.
+
+
+[1]: https://github.com/heptio/contour/issues/1184
+[2]: https://github.com/heptio/contour/issues/1185