Edit this page

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 as amqps or ssl.
  • validateCertificates: Must be true.
  • 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 as ssl.

  • credentials/type: Must be client-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
Tags: connectivity