Secure connections to targets

At the end of this guide, an outbound target sends its data over TLS: the target checks the server it connects to, and, where the server asks for it, proves who it is with a client certificate. You set this up once per target. The certificates live in the Certificate Store, so renewing one there needs no change on the target.

Before you start

• The target exists. Outbound targets shows how to create one.
• You can open Security > Certificate Store.
• You have the files your server's administrator or cloud service gave you: usually a CA certificate, and for a client certificate the certificate and its private key, in PEM format (.pem, .crt, .key) or as a .pfx.

The two certificates of a target

There are two ways to put the certificates in place:

1. On the target page: select Certificates and choose the client certificate, its private key and, if you have it, the CA certificate, all at once. Proxus finds out which file is which: the certificate that matches the private key becomes the client certificate, and another certificate among the files becomes the trusted server certificate. Both go into the Certificate Store and the target refers to them.
2. In the Certificate Store: select Upload and choose the files. A certificate without a key (a CA) is stored as a public certificate. Then pick the certificates on the target:
   • For MQTT, AWS IoT Core and SparkplugB, select Edit Parameters and choose them in Client Certificate and Trusted Server Certificate.
   • For the other types, add the parameter ServerCertificateThumbprint (and CertificateThumbprint for a client certificate) to the target. The value is the certificate's Thumbprint: open the certificate in the store to copy it.

After any change, open the target, select Check, choose in Run Probe On the gateway that sends the data, and select Test Connection. It uses the same certificates and the same checks as real deliveries.

AWS IoT Core

AWS IoT Core always uses mutual TLS on port 8883: the target needs the thing's device certificate and its key.

In the AWS console

1. Open AWS IoT Core > Manage > All devices > Things and select Create things. Create a single thing, for example proxus-line-1.

2. In the certificate step, select Auto-generate a new certificate.

3. Attach a policy that lets the thing connect and publish. A minimal policy for a client ID equal to the thing name and the topic proxus_device_data:

   {
     "Version": "2012-10-17",
     "Statement": [
       { "Effect": "Allow", "Action": "iot:Connect",
         "Resource": "arn:aws:iot:<region>:<account>:client/proxus-line-1" },
       { "Effect": "Allow", "Action": "iot:Publish",
         "Resource": "arn:aws:iot:<region>:<account>:topic/proxus_device_data" }
     ]
   }

4. Download the three files AWS offers: the device certificate (…-certificate.pem.crt), the private key (…-private.pem.key) and Amazon Root CA 1 (AmazonRootCA1.pem). The private key can be downloaded only on this page.

5. Open Settings and copy the Device data endpoint, for example a1b2c3d4e5-ats.iot.eu-central-1.amazonaws.com.

In Proxus

1. Open the AWS IoT Core target (clone the AWS IoT Core sample if you have none) and save it once.

2. Select Certificates and choose the three files together. The device certificate is stored with its key and becomes the Client Certificate; Amazon Root CA 1 becomes the Trusted Server Certificate. If you choose only the certificate and the key, Proxus downloads Amazon Root CA 1 itself. Without internet access from the hub, the operating system's trusted roots check AWS instead.

3. Select Edit Parameters and fill in:

   • Endpoint: the device data endpoint from step 5.
   • Client Id: the client ID the policy allows, here proxus-line-1.
   • Port 8883 and Use TLS on (both are the defaults).
   • Topic: a topic the policy allows.

   Client Certificate and Trusted Server Certificate are already filled in.

4. Save, select Check, choose the sending gateway in Run Probe On and select Test Connection.

MQTT brokers (Mosquitto, EMQX, HiveMQ and others)

1. Find out the broker's TLS port (usually 8883) and who signed its certificate.
2. If the broker's certificate comes from your own CA, upload the CA certificate to the Certificate Store. If it comes from a public CA, skip this step.
3. If the broker requires client certificates (require_certificate true in Mosquitto), get a client certificate and key from the broker's administrator and upload them with Certificates on the target.
4. On the target, select Edit Parameters:
   • Broker Host: the name in the broker's certificate. An IP address works only if the certificate contains it.
   • Broker Port 8883, Use TLS on, Tls Version Tls12 (or Tls13 if the broker supports it).
   • Trusted Server Certificate: the CA from step 2, or empty for a public CA.
   • Client Certificate: the certificate from step 3, or empty.
5. Save and run Test Connection.

To send to the MQTT broker of another Proxus gateway, choose Proxus Platform CA as the trusted server certificate: every gateway's broker certificate is issued by it.

SparkplugB targets have the same fields and work the same way.

Kafka

Add these parameters to the target:

The broker's host name is checked against its certificate.

RabbitMQ

Redis

ClickHouse

Set UseTls to true. The target then uses HTTPS on port 8443 unless you set Port. Add ServerCertificateThumbprint for a private CA and CertificateThumbprint if the server requires a client certificate.

REST API, InfluxDB and Splunk

A URL that starts with https:// is TLS; the server's certificate is checked against it. Nothing else is needed for a server with a public CA certificate. For a private CA, add ServerCertificateThumbprint; for a client certificate, add CertificateThumbprint.

For Splunk, enter the HTTP Event Collector address with https://, for example https://splunk.example.com:8088. The older UseSSL parameter has no effect.

PostgreSQL and MySQL

When SslMode is not set, the database driver's default applies, which encrypts when the server offers it but does not check the server. Client certificates are not supported for these two databases.

Azure IoT Hub

The connection always uses TLS on port 8883. The hub is checked against the operating system's trusted roots, and the device signs in with its SharedAccessKey. No certificate is needed. X.509 device authentication is not supported in this version.

Targets that do not use the Certificate Store

When the connection fails

What's next

• Outbound targets: transport strategy, checking a target, choosing devices.
• Certificate Store: renewing, replacing and removing certificates.
• Outbound targets reference: every parameter of every target type.