# Encrypting Traffic Between Collectors and Gateways {% hint style="info" %} **OTLP Source and Destination** The Bindplane Gateway Source and Destination are OTLP-based. The TLS configuration described in this guide applies equally to the **OTLP Source** and **OTLP Destination** — the same UI fields, parameters, and behavior apply to both. {% endhint %} For certificate format requirements, see [Certificate and Key Requirements](/how-to-guides/security-and-tls/using-tls/requirements.md). For mutual TLS details, see the [Mutual TLS Guide](/how-to-guides/security-and-tls/using-tls/mutual-tls.md). ## Overview In this architecture, downstream collectors send telemetry data to one or more gateway hosts: ``` Downstream Collector(s) Gateway Host(s) ┌─────────────────────┐ ┌─────────────────────┐ │ Bindplane Gateway │── TLS ──────>│ Bindplane Gateway │ │ Destination │ │ Source │ │ (TLS Client) │ │ (TLS Server) │ └─────────────────────┘ └─────────────────────┘ ``` The **Gateway Source** acts as a TLS server, presenting a certificate to incoming connections. The **Gateway Destination** acts as a TLS client, verifying the server's certificate. ## Prerequisites Before configuring TLS, ensure you have the following files ready on the appropriate hosts: **On the gateway host(s):** * Server certificate in PEM format (can include the full certificate chain) * Server private key in PEM format, unencrypted **On the downstream collector(s):** * CA certificate that signed the gateway's server certificate (not needed if using a publicly trusted CA) **For mutual TLS (optional):** * Client certificate and key on each downstream collector * Client CA certificate on the gateway host {% hint style="warning" %} **Certificate Requirements** * Only PEM format is supported (not DER or PKCS#12/PFX) * Private keys must be unencrypted (no password protection) * If your CA uses intermediates, create a fullchain file with the leaf cert first: `cat server.crt intermediate.crt > fullchain.crt` See [Certificate and Key Requirements](/how-to-guides/security-and-tls/using-tls/requirements.md) for details. {% endhint %} ## Step 1: Configure the Gateway Source (Server Side) The gateway host runs a configuration with the Bindplane Gateway Source, which listens for incoming telemetry over OTLP (gRPC on port 4317, HTTP on port 4318 by default). ### Using the Bindplane UI 1. Edit the configuration used by your gateway host(s) 2. Select the **Bindplane Gateway** source 3. Expand the **Advanced** section 4. Check **Enable TLS** 5. Set **TLS Certificate Path** to the path of your server certificate or fullchain file (e.g., `/etc/collector/certs/fullchain.crt`) 6. Set **TLS Private Key Path** to the path of your unencrypted private key (e.g., `/etc/collector/certs/server.key`) ### UI Field Reference | Bindplane UI Field | Description | | -------------------- | ----------------------------------------------------------- | | Enable TLS | Enables TLS on the Gateway Source listener | | TLS Certificate Path | Server certificate file (can include full chain) | | TLS Private Key Path | Server private key file (must be unencrypted) | | CA File | CA for optional client verification (does not enforce mTLS) | | Client CA File | CA that enforces mTLS (rejects clients without valid certs) | ### File Permissions Set appropriate permissions on the gateway host: {% tabs %} {% tab title="Linux/macOS" %} ```bash chmod 600 /etc/collector/certs/server.key chown : /etc/collector/certs/server.key chmod 644 /etc/collector/certs/fullchain.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell icacls C:\certs\server.key /inheritance:r /grant:r "$($env:USERNAME):(R)" # Certificate files can remain with default permissions ``` {% endtab %} {% endtabs %} ## Step 2: Configure the Gateway Destination (Client Side) Each downstream collector runs a configuration with the Bindplane Gateway Destination, which connects to the gateway host over OTLP. ### Using the Bindplane UI 1. Edit the configuration used by your downstream collector(s) 2. Select the **Bindplane Gateway** destination 3. Set **Enable TLS** to true 4. Set **TLS Certificate Authority File** to the CA certificate that signed the gateway's server certificate (e.g., `/etc/collector/certs/ca.crt`) {% hint style="info" %} **When is the CA file needed?** * **Private/internal CA**: You must provide the CA certificate file so the downstream collector can verify the gateway's certificate. * **Publicly trusted CA** (e.g., Let's Encrypt, DigiCert): The system trust store already contains the root CA, so you may not need to specify a CA file. {% endhint %} ### UI Field Reference | Bindplane UI Field | Description | | ---------------------------------- | --------------------------------------------------------------------------------------- | | Enable TLS | Enables TLS for the outbound connection to the gateway | | Skip TLS Certificate Verification | Skips server certificate validation (not recommended for production) | | TLS Certificate Authority File | CA certificate to verify the gateway's server certificate | | Server Name Override | Override the expected server hostname in the certificate (useful when connecting by IP) | | Mutual TLS | Enables client certificate authentication | | Mutual TLS Client Certificate File | Client certificate presented to the gateway | | Mutual TLS Client Private Key File | Client private key (must be unencrypted) | ### Hostname and Certificate Matching The **hostname** configured in the Gateway Destination must match either the Common Name (CN) or a Subject Alternative Name (SAN) in the gateway's TLS certificate. If you need to connect by IP address but your certificate uses a hostname, set the **Server Name Override** field to the hostname in the certificate. ## Step 3: Verify the Connection After deploying the updated configurations, verify TLS is working from a downstream collector host: {% tabs %} {% tab title="Linux/macOS" %} ```bash openssl s_client -connect :4317 ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell openssl s_client -connect :4317 ``` {% endtab %} {% endtabs %} You should see: * The gateway's certificate chain displayed * `Verify return code: 0 (ok)` If using a private CA, specify the CA file: {% tabs %} {% tab title="Linux/macOS" %} ```bash openssl s_client -connect :4317 -CAfile /path/to/ca.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell openssl s_client -connect :4317 -CAfile C:\certs\ca.crt ``` {% endtab %} {% endtabs %} ## Optional: Adding Mutual TLS (mTLS) Standard TLS only verifies the gateway's identity to the downstream collectors. Mutual TLS adds the reverse — the gateway also verifies each downstream collector's identity. ### When to Use mTLS * You need to restrict which collectors can send data to the gateway * Compliance requires two-way authentication * You want to authenticate collectors by certificate rather than IP address ### Gateway Source (Server Side) Add the **Client CA File** to enforce mTLS. This causes the gateway to reject any connection that does not present a valid client certificate signed by this CA. In the Bindplane UI: 1. Edit the gateway configuration's source 2. In the Advanced section, set **Client CA File** to the CA certificate that signed your client certificates (e.g., `/etc/collector/certs/client-ca.crt`) {% hint style="warning" %} **`ca_file` vs `client_ca_file`** * **CA File** (`ca_file`): Optional client verification — collectors without certificates can still connect * **Client CA File** (`client_ca_file`): Enforced mTLS — all collectors must present valid certificates Use **Client CA File** if you want to enforce mTLS. See the [Mutual TLS Guide](/how-to-guides/security-and-tls/using-tls/mutual-tls.md) for details. {% endhint %} ### Gateway Destination (Client Side) On each downstream collector, enable mutual TLS and provide the client certificate: 1. Edit the downstream configuration's destination 2. Enable **Mutual TLS** 3. Set **Mutual TLS Client Certificate File** to the client certificate (e.g., `/etc/collector/certs/client.crt`) 4. Set **Mutual TLS Client Private Key File** to the client private key (e.g., `/etc/collector/certs/client.key`) ### Verify mTLS Test that the gateway accepts connections with a valid client certificate: {% tabs %} {% tab title="Linux/macOS" %} ```bash openssl s_client -connect :4317 \ -cert client.crt \ -key client.key \ -CAfile ca.crt ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell openssl s_client -connect :4317 ` -cert C:\certs\client.crt ` -key C:\certs\client.key ` -CAfile C:\certs\ca.crt ``` {% endtab %} {% endtabs %} Test that the gateway rejects connections without a client certificate: {% tabs %} {% tab title="Linux/macOS" %} ```bash # This should fail with "certificate required" or "handshake failure" openssl s_client -connect :4317 ``` {% endtab %} {% tab title="Windows PowerShell" %} ```powershell # This should fail with "certificate required" or "handshake failure" openssl s_client -connect :4317 ``` {% endtab %} {% endtabs %} ## Troubleshooting | Symptom | Cause | Solution | | ----------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Unknown CA" from downstream collectors | Missing intermediate certificates in the gateway's cert file | Create a fullchain: `cat server.crt intermediate.crt > fullchain.crt` and use it as the TLS Certificate Path on the gateway source | | "Failed to load TLS cert and key" on the gateway | Encrypted private key or non-PEM format | Decrypt with `openssl rsa -in encrypted.key -out decrypted.key`, or convert from DER with `openssl x509 -inform DER -in cert.der -out cert.pem` | | "Certificate and key do not match" on the gateway | Wrong key file paired with the certificate | Verify they match: `openssl x509 -noout -modulus -in server.crt \| openssl md5` and `openssl rsa -noout -modulus -in server.key \| openssl md5` — hashes must be identical | | TLS handshake timeout | TLS version incompatibility | Ensure both sides support TLS 1.2+; check `min_version` on the gateway source | | Downstream collectors connect without certs when mTLS is expected | Using `ca_file` instead of `client_ca_file` on the gateway source | Switch to **Client CA File** (`client_ca_file`) to enforce mTLS | | "Certificate required" errors from downstream collectors | mTLS is enforced but the destination doesn't have client certs configured | Enable Mutual TLS on the Gateway Destination and provide the client certificate and key | For additional troubleshooting, see the [TLS Troubleshooting Guide](/how-to-guides/security-and-tls/using-tls/troubleshooting.md). ## Related Resources * [Certificate and Key Requirements](/how-to-guides/security-and-tls/using-tls/requirements.md) * [TLS Configuration Guide](/how-to-guides/security-and-tls/using-tls/configuration.md) * [Mutual TLS Guide](/how-to-guides/security-and-tls/using-tls/mutual-tls.md) * [Testing and Verification](/how-to-guides/security-and-tls/using-tls/reference/testing-verification.md) * [Bindplane Gateway Source Documentation](https://docs.bindplane.com/integrations/sources/bindplane-gateway) * [Bindplane Gateway Destination Documentation](https://docs.bindplane.com/integrations/destinations/bindplane-gateway) * [OpenTelemetry (OTLP) Source Documentation](https://docs.bindplane.com/integrations/sources/opentelemetry) * [OpenTelemetry (OTLP) Destination Documentation](https://docs.bindplane.com/integrations/destinations/opentelemetry-otlp) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bindplane.com/how-to-guides/security-and-tls/using-tls/gateway-tls.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.