SSL
Last updated
Was this helpful?
1.2
Last updated
Was this helpful?
are a set of protocols designed to ensure secure communication across a network. Envoy's and Greymatter's filters allow for diverse types of TLS connections throughout the mesh. This document explains the different types of supported TLS and technical steps on how to configure them within Greymatter.
In One-Way TLS, only one certificate trust file is evaluated: either the client's or the server's. This can be configured with different values in the cluster vs. domain objects. Crucially, the domain configures TLS parameters (e.g. certificates, ssl types) for incoming requests whereas the cluster object controls TLS setting used for outward requests leaving the proxy.
To validate client trust certificates, add the "trust_file" parameter to the domain object.
To validate server trust certificates, add the "trust_file" parameter to the cluster object.
Mutual TLS is a type of TLS communication where the server and client both verify each other's certificates during the TLS handshake, hence it is more secure than one way TLS. In its , this is a form of where the incoming request context is terminated and the outgoing request is formed from a new certificate pair.
To add mTLS to your mesh, the following configuration needs to applied to each domain (incoming requests to the proxy)
and cluster (outgoing requests from the proxy):
A common use case of sidecars is to change the incoming protocol to something that can be used by the backed service. This gives assurance that upstream requests will be of a compatible type certain with each service's supported protocols.
Origination occurs when a http context is "upgraded" to https. To enable origination, we first need to allow incoming http requests checks to pass validation. This can be done by updating the TLS options in the domain to look like the following:
This removes TLS checks on incoming requests. Then, we need to configure outgoing requests to use a TLS context. This can be done by updating the cluster to look like the following:
This ensures that outgoing requests from the proxy will use a TLS context from the provided certificates.
Termination occurs when a https context is "downgraded" to http, the opposite of origination. To enable termination, we need to first ensure that incoming requests are validated with a TLS security context. This is done by updating the domain to use the following TLS configs:
Now, we need to tell each gm-proxy instance to use plain http for outgoing requests. This is done by removing TLS configs from the cluster:
Incoming requests must now be TLS and outgoing requests from the proxy will be in plain http.
Instantiate a listener on localhost:80 using TLS origination
Perform a request curl http://localhost:80. By default, the header is set as x-forwarded-proto: http
Sidecar receives the request, converts it to an SSL request, finds the correct cluster, and proxies the request.
The upstream service receives the request, performs the SSL handshake, reads the request, sees that x-forward-proto: http. The service is confused because it doesn't handle http and issues a 301 redirect back.
There are two ways of ensuring that the right x-forwarded-proto header is set for outgoing requests:
Specify x-forwarded-proto in each incoming request. This is not recommended for deployments or as a long term solution.
Add x-forwarded-proto as a custom header in the domain. Here is an example of setting this for origination:
Now, every outgoing request using this domain will include the header "x-forwarded-proto: https".
listener:localhost:80 domain: configured to accept http requests
listener:localhost:443 domain: configured to accept https requests
After an incoming request is validated by the corresponding domain, it is routed to the corresponding cluster, using the cluster's specified TLS configuration.
Together, adding different types listeners and specifying the protocol for each cluster allows for powerful and dynamic configuration of TLS for each service (i.e. mTLS, one-way TLS, origination, etc).
This forces each gm-proxy instance to serve https and validate incoming requests from a given certificate pair. For more information on SSL configuration parameters, see documentation for and TLS configs.
SSL Passthrough differs from other methods for implementing TLS. Instead of handling encryption / decrypting at the proxy, the tls configuration is forwarded "as is." No actions are taken such as access control, redirects, blocking, or cookie / session management. The responsibility for this logic is deferred downstream to the workload.
At this writing, envoy does not support generic tls passthrough. It does support to connect directly to tcp or grpc servers directly. To enable this, see of setting up .
When making requests to services which change protocols, the header should be set explicitly. Otherwise, if set implicitly, it will default to the original client protocol. When the upstream service receives the request, it will examine the x-forwarded-proto value and think the request is not the right protocol. The request will be rejected with a 301 redirect. Here is an example of this workflow:
Each type of TLS listed here can be combined with multiple on one sidecar. For example, a sidecar handling both plaintext and encrypted traffic has two listeners. Each listener uses a different domain to control how to handle incoming requests: