TLS Certificates

Edit this page

You use TLS certificates to secure connections between Ditto and external message brokers, verifying server identity and optionally authenticating Ditto as a client.

TL;DR: Set validateCertificates: true and provide a ca certificate to verify server identity. Add credentials with type client-cert to authenticate Ditto with a client certificate.

Overview

Ditto supports two certificate-based security features:

Server certificate verification – confirms the identity of the external endpoint
Client certificate authentication – authenticates Ditto at the external endpoint

Both features are available for AMQP 0.9.1, AMQP 1.0, MQTT 3.1.1, MQTT 5, HTTP 1.1, and Kafka 2.x connections.

How it works

Server certificate verification

Verifying the server identity mitigates man-in-the-middle attacks. To enable it, use a secure transport protocol and set validateCertificates to true:

{
  "uri": "<secure-protocol>://<host>:<port>/<path>",
  "validateCertificates": true,
  "ca": "-----BEGIN CERTIFICATE-----\n<trusted certificate>\n-----END CERTIFICATE-----"
}

Field	Description
`uri`	Use a secure protocol such as `amqps`, `ssl`, or `https`
`validateCertificates`	Must be `true`
`ca`	Trusted certificates as PEM-encoded DER. Concatenate multiple certificates to trust all of them. Omit to trust public CAs.

Ditto verifies the server identity in one of three ways:

Direct verification – the exact server certificate is in the ca field. TLS proves the server possesses the matching private key.

Indirect verification via trusted party – the server certificate is signed by a CA whose certificate is in the ca field, and the connection URI hostname matches the server certificate (as CN or SAN). IPv4/IPv6 addresses must be listed as a SAN of type IP per RFC-5280. Revocation of individual certificates is not supported.

Indirect verification via public CAs – the ca field is omitted, and the server certificate is signed by a generally accepted CA. Ditto attempts to exclude revoked certificates via OCSP.

Note: Certificates signed by public CAs get compromised on a daily basis. It is more secure to upload your message broker’s certificate directly even if it was signed by a public CA. Then the Ditto connection trusts only your broker (or rather any holder of the broker’s private key). To minimize unavailability due to certificate expiry, upload both: the current broker certificate and the next certificate as a concatenated string.

Client certificate authentication

Client-certificate authentication is available for MQTT, HTTP, AMQP 1.0, and Kafka 2.x connections.

Configure a client certificate to authenticate Ditto at your message broker:

{
  "uri": "<secure-protocol>://<host>:<port>/<path>",
  "credentials": {
    "type": "client-cert",
    "cert": "-----BEGIN CERTIFICATE-----\n<client certificate>\n-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----\n<client private key>\n-----END PRIVATE KEY-----"
  }
}

Field	Description
`credentials/type`	Must be `client-cert`
`credentials/cert`	Client certificate as PEM-encoded DER
`credentials/key`	Client private key as PEM-encoded PKCS8 per RFC-7468. The PEM preamble must be `-----BEGIN PRIVATE KEY-----`.

Converting PKCS1 keys to PKCS8

OpenSSL and AWS IoT generate PKCS1 keys by default (-----BEGIN RSA PRIVATE KEY-----), which Ditto rejects. Convert with:

openssl pkcs8 -topk8 -nocrypt -in client-private.pem.key -out client-private.pem.pk8