Secrets

• Secrets

  • Upstream/Downstream

    • Upstream

    • Downstream

      • Forward Client Cert Details

      • Set Current Client Cert Details

  • SDS

    • Gotchas

Secrets inside the Grey Matter Fabric Mesh enable easy SSL configuration by removing the need to pass around certificates as files. Utilizing Envoy's SDS (Secret Discovery Service), Grey Matter manages it's certificate/key rotation, as well as distribution of certs through any SDS compliant server. We support the following:

• SPIFFE/SPIRE

• User Defined Secrets

For more in-depth information on how Envoy's SDS works, visit the following link.

Secrets in the mesh are defined as the following:

"secret" : {
  "secret_key": "secret-web-secret",
  "secret_name": "spiffe://deciphernow.com/web_proxy/mTLS",
  "secret_validation_name": "spiffe://deciphernow.com",
  "subject_alt_name": "spiffe://deciphernow.com/echo_proxy/mTLS",
  "ecdh_curves": [
    "X25519:P-256:P-521:P-384"
  ],
  "set_current_client_cert_details": {
    "uri": false
  }
}

The key is strictly used inside of Grey Matter and should be unique to the secret that will bind itself to the TLSContext within Envoy.

"secret_key": "secret-web-secret"

Secret names are identities that live within the cert pool of Envoy. A name should correspond to one certificate that Envoy has registered, and will be used when querying the SDS API.

"secret_name": "spiffe://deciphernow.com/web_proxy/mTLS"

When performing 2-Way SSL, Subject Alternative Names are required for client certificate verification. Without this configuration option, Envoy will not understand what certificate to verify when it attempts to connect to it's upstream/downstream host.

"subject_alt_name": "spiffe://deciphernow.com/echo_proxy/mTLS"

ValidationNames are used to verify a certificate in the Envoy cert pool against a Certificate Authority.

"secret_validation_name": "spiffe://deciphernow.com"

If specified, the TLS connection established when using secrets, will only support the specified ECDH curves. If not specified, the default curves will be used within Envoy.

"ecdh_curves": [
  "X25519:P-256:P-521:P-384"
]

Upstream/Downstream

Secrets may be set on Upstream or Downstream TLS contexts. Within the Grey Matter Fabric Mesh, this means that clusters, as well as listeners may have secrets bound to them.

Upstream

Upstream secrets apply to Envoy's Cluster objects. Examples on how to configure these options can be found here.

Downstream

Downstream secrets have a few more configuration options that enable extra features within the Envoy config:

"forward_client_cert_details": "",
"set_current_client_cert_details": {
    "uri": false
}

Examples on how to configure downstream secrets on Envoy listener objects can be found here.

Forward Client Cert Details

The possible options when forwarding client cert details are:

• "SANITIZE"

• "SANITIZE_SET"

• "FORWARD_ONLY"

• "APPEND_FORWARD"

• "ALWAYS_FORWARD_ONLY"

This field specifies how to handle the x-forwarded-client-cert (XFCC) HTTP header.

Set Current Client Cert Details

set_current_client_cert_details is valid only when forward_client_cert_details is APPEND_FORWARD or SANITIZE_SET and the client connection is mTLS. It specifies the fields in the client certificate to be forwarded. Note that in the x-forwarded-client-cert header, Hash is always set, and By is always set when the client certificate presents the URI type Subject Alternative Name value.

SDS

The most important benefit of the Secret Discovery Service (SDS) is to simplify the certificate management. Without this feature, certificates must be created as secrets and mounted into the proxy containers. If certificates are expired, the secrets need to be updated and the proxy containers need to be re-deployed. With SDS, a central SDS server will push certificates to all Envoy instances. If certificates are expired, the server just pushes new certificates to Envoy instances, Envoy will use the new ones right away without a need for re-deployment.

Gotchas

• If a static cluster is using SDS, and it needs to define a SDS cluster (unless Google gRPC is used which doesn’t need a cluster), the SDS cluster has to be defined before the static clusters using it.

• The connection between Envoy proxy and SDS server has to be secure. One option is to run the SDS server on the same host and use Unix Domain Socket for the connection. Otherwise the connection requires TLS with authentication between the proxy and SDS server. Credential types in use today for authentication are:

  • mTLS – In this case, the client certificates for the SDS connection must be statically configured.

  • AWS IAM SigV4