Secure Device Authentication with X.509 Certificates in Eclipse Hono

In recent months, media coverage has highlighted insecure IoT devices that fail to meet basic security standards. A recurring concern is the confidentiality of data transmitted from devices to cloud services. Surprisingly, many devices send data over public networks unencrypted, even though TCP/IP‑based protocols like HTTP and MQTT support TLS encryption.

Eclipse Hono has enabled TLS for its HTTP and MQTT adapters since the outset. The 0.9‑M2 milestone now adds support for X.509 client‑certificate authentication during the TLS handshake, allowing devices to use a key pair instead of a username/password.

Calling all developers

Europe’s largest IoT hackathon returns to Berlin on May 14‑15 2023. Join 700+ developers in domain‑specific challenges, learn, network, and have fun.

In this guide we walk through a complete example: create and register a tenant‑specific trust anchor, generate a device certificate, register its subject DN, and use the certificate to authenticate the device against Hono’s MQTT adapter. A working knowledge of RSA cryptography and X.509 concepts (RFC 5280) is assumed.

Why client certificates?

Using passwords requires storing a secret per device in Hono’s Credentials service, which is then compared to the device’s supplied password. Client certificates eliminate the need for per‑device secrets. By registering a single trust anchor for a tenant, all device certificates can be validated in the TLS handshake using the tenant’s public key.

Create a tenant certificate authority

Generate the tenant’s RSA key pair and self‑signed certificate. These will sign all device certificates.

$ openssl genrsa -out tenant-key.pem 4096
$ openssl req -x509 -key tenant-key.pem -out tenant-cert.pem -days 365 -subj "/O=ACME Inc./CN=Sensors"

Use only standard X.500 attributes (CN, L, ST, O, OU, C, STREET, DC, UID) to keep the DN simple.

Register the tenant

Register the trust anchor with Hono. The following example uses the Hono Sandbox (v0.9‑M2 or later). Replace ACME with a unique tenant ID for your instance.

$ TENANT="ACME"
$ SUBJECT=$(openssl x509 -in tenant-cert.pem -noout -subject -nameopt RFC2253 | sed s/^subject=//)
$ PK=$(openssl x509 -in tenant-cert.pem -noout -pubkey | sed /^---/d | sed -z 's/\\n//g')
$ cat < tenant.json
{
  "tenant-id": "$TENANT",
  "trusted-ca": {
    "subject-dn": "$SUBJECT",
    "public-key": "$PK"
  }
}
EOS
$ curl -i -H "Content-Type: application/json" -H "Expect:" --data-binary @tenant.json https://hono.eclipse.org:28443/tenant

Create a device certificate

Generate a device key pair and a certificate signed by the tenant’s CA.

$ openssl genrsa -out device-key.pem 4096
$ openssl req -new -key device-key.pem -subj "\/O=ACME Inc.\/CN=Hot Fuzz Device" | \
  openssl x509 -req -days 365 -out device-cert.pem -CA tenant-cert.pem -CAkey tenant-key.pem -CAcreateserial

Register the device

Register a device ID with the tenant.

$ curl -i -H "Content-Type: application/json" --data-binary '{"device-id":"hot-fuzz"}' https://hono.eclipse.org:28443/registration/$TENANT

Register the device’s subject DN

Associate the device certificate’s subject DN with the device ID.

$ SUBJECT=$(openssl x509 -in device-cert.pem -noout -subject -nameopt RFC2253 | sed s/^subject=//)
$ cat < credentials.json
{
  "device-id": "hot-fuzz",
  "type": "x509-cert",
  "auth-id": "$SUBJECT",
  "secrets": [{}]
}
EOS
$ curl -i -H "Content-Type: application/json" --data-binary @credentials.json https://hono.eclipse.org:28443/credentials/$TENANT

Test the connection

Start a consumer for the tenant and publish telemetry using the device certificate.

# Start consumer
java -jar hono-cli-*-exec.jar \
  --hono.client.host=hono.eclipse.org \
  --hono.client.port=15671 \
  --hono.client.tlsEnabled=true \
  --hono.client.username=consumer@HONO \
  --hono.client.password=verysecret \
  --spring.profiles.active=receiver \
  --tenant.id=$TENANT

# Publish telemetry via MQTT
mosquitto_pub -h hono.eclipse.org -p 8883 \
  --capath /etc/ssl/certs/ \
  --cert device-cert.pem \
  --key device-key.pem \
  -q 1 -t telemetry -m "Hello there"

If successful, the consumer console will display the message. You can also publish via HTTP:

curl -i --cert device-cert.pem --key device-key.pem \
  -H "Content-Type: plain/text" -H "Expect:" \
  --data-binary "Hello there" https://hono.eclipse.org:8443/telemetry