Verify server certificate
Server-certificate verification is available for AMQP 0.9.1, AMQP 1.0, MQTT 3.1.1, MQTT 5, HTTP 1.1, and Kafka 2.x connections.
Connection configuration
Verifying the server identity mitigates the risk of man-in-the-middle attacks.
To have Ditto check the identity of external message brokers,
choose a secure transport protocol and set the flag validateCertificates
to true
in your
connections.
{
"uri": "<secure-transport-protocol>://<host>:<port>/<path>",
"validateCertificates": true,
"ca": "-----BEGIN CERTIFICATE-----\n<trusted certificate>\n-----END CERTIFICATE-----"
}
uri
: Choose a secure transport protocol such asamqps
orssl
.validateCertificates
: Must betrue
.ca
: A string of trusted certificates as PEM-encoded DER. Concatenate multiple certificates as strings to trust all of them. Omit to trust popular certificate authorities.
Server identity check
When Ditto opens a secure connection, the external message broker provides a server certificate. The server identity is verified directly or indirectly.
-
Direct identity verification: The exact server certificate is listed as a trusted certificate in the connection configuration
ca
. Establishing a TLS session proves that the external message broker possesses the private key matching the server certificate. -
Indirect identity verification via a trusted party: The server certificate is signed by a trusted party, whose certificate is in the connection configuration
ca
, and the host-component of the connection URI is listed in the server certificate.If the host-component is a DNS name, then it should be listed as the common name (CN) or a subject alternative name (SAN) of type DNS.
If the host-component is an IPv4 or IPv6 address, then it should be listed as a subject alternative name (SAN) of type IP. Any IP addresses in the common name (CN) are ignored per RFC-5280.
Revocation of individual certificates is not supported. For each certificate in the
ca
field, you extend trust to all certificates signed by it. -
Indirect identity verification via public certificate authorities: The server certificate is signed by a generally accepted certificate authority, the host-component of the connection URI is listed in the server certificate, and the
ca
field is omitted in the connection configuration.Ditto will try its best to exclude revoked certificates via OCSP.
Authenticate by client certificate
Client-certificate authentication is available for MQTT connections and HTTP connections only.
Connection configuration
Configure a client certificate for Ditto in the credentials
field of the connection configuration to authenticate
Ditto at your message broker.
{
"uri": "<secure-transport-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-----"
}
}
-
uri
: Choose a secure transport protocol such asssl
. -
credentials/type
: Must beclient-cert
. -
credentials/cert
: The client certificate as PEM-encoded DER. -
credentials/key
: The client private key for Ditto as PEM-encoded PKCS8 specified by RFC-7468; the PEM preamble must be-----BEGIN PRIVATE KEY-----
.
As of September 2018, OpenSSL and AWS IoT generate PKCS1-coded private keys by default, which
have the PEM preamble -----BEGIN RSA PRIVATE KEY-----
. Ditto will reject these keys. The command below converts a
PKCS1 key file client-private.pem.key
into a PKCS8 key file client-private.pem.pk8
accepted by Ditto.
openssl pkcs8 -topk8 -nocrypt -in client-private.pem.key -out client-private.pem.pk8