Securing gRPC communication

Defguard Core has two main communication endpoints:

1. gRPC port for communicating with Defguard Gateways,

2. gRPC port for communicating with Defguard Core.

It is critical that:

1. Defguard Core's gRPC port is open on a firewall only for IP addresses of Defguard Gateway nodes.

2. Defguard Proxy's gRPC port is open on a firewall only for the IP address of Defguard Core.

3. If you want an additional layer of security, then you should create a custom SSL Certificate Authority (CA), and provide Core, Proxy and Gateway Certificates from that CA so any other connections to the gRPC services will not be accepted.

4. Even if you have secured the network ports/firewall and do not want to create a custom SSL CA, please secure gRPC traffic with SSL and a reverse proxy.

Custom SSL CA and certificates

To secure not only with firewall communication between all Defguard gRPC components, a custom SSL chain of certificates should be used. This way the trust will be ensured on the Transport Layer Security (TLS) level.

It is important to embed a correct domain name into the certificate as X509v3 Subject Alternative Name. The domain name must match the one under which a service is being hosted.

Quick setup

To quickly generate a set of SSL certificates using OpenSSL or LibreSSL, use the following:

• Generate Certificate Authority (CA) cerfiticate and key for domain example.local

openssl req -x509 -noenc -subj '/CN=example.local' -newkey rsa:4096 -keyout ca.key -out ca.crt

• Generate private key and Certificate Signing Request (CSR)

openssl req -noenc -newkey rsa:4096 -keyout core.key -out core.csr -subj '/CN=example.local' -addext subjectAltName=DNS:example.local

• Generate certificate by signing the CSR, valid for 365 days

openssl x509 -req -in core.csr -CA ca.crt -CAkey ca.key -days 365 -out core.crt -copy_extensions copy

Repeat the last two steps for other services (e.g. change core.csr, core.crt, and core.key to gateway.csr, gateway.crt, gateway.key), just change the domain name accordingly.

To display certificate file contents:

openssl x509 -noout -text -in core.crt

Defguard configuration

Defguard Core

Using command line arguments

defguard --grpc-cert path/to/core.crt \
         --grpc-key path/to/core.key \
         --proxy-grpc-ca path/to/ca.crt

Using environment variables

env DEFGUARD_GRPC_CERT=path/to/core.crt \
    DEFGUARD_GRPC_KEY=path/to/core.key \
    DEFGUARD_PROXY_GRPC_CA=path/to/ca.crt \
    defguard

Defguard Proxy

Using command line arguments

defguard-proxy --grpc-cert path/to/proxy.crt \
               --grpc-key path/to/proxy.key

Using environment variables

env DEFGUARD_PROXY_GRPC_CERT=path/to/proxy.crt \
    DEFGUARD_PROXY_GRPC_KEY=path/to/proxy.key
    defguard-proxy

Defguard Gateway

Using command line arguments

defguard-gateway --grpc-ca path/to/ca.crt

Using environment variables

env DEFGUARD_GRPC_CA=path/to/ca.crt \
    defguard-gateway

Using configuration file

grpc_ca = "path/to/ca.crt"

Trusted CA (eg. Let'sEncrypt or others)

Often (like in the standalone package based installation tutorial) gRPC communication can be secured by a reverse proxy (NGINX, Caddy, Traefik, etc.) that handles SSL termination. It's common to use typical trusted CA (that is used for typical HTTPS traffic) like Let'sEncrypt or others.

While this secures the transport layer and encrypts communication between defguard components - it does not provide authorization between gRPC components like Custom CA does.

Thus, this type of SSL termination should only be done if you trust your network and have secured gRPC ports on firewall.

If Defguard Core or Defguard Proxy are using reverse proxy with SSL termination, then only you need to configure CA certificate paths for:

• Defguard Gateway – in gateway.toml add path to CA certificate file (in PEM format); for example when using standard Let'sEncrypt installation (Certbot), you configure the CA path like this:

  • grpc_ca = "/etc/letsencrypt/live/domain.name/chain.pem"

• Defguard Core – similarily, you need to configure Proxy CA certificate file using DEFGUARD_PROXY_GRPC_CA environment variable:

  • DEFGUARD_PROXY_GRPC_CA: /etc/letsencrypt/live/domain.name/chain.pem