Subscribe Find out first about new and important news
  • Share via email
  • Subscribe to blog alert

X.509 based device authentication in Eclipse Hono

During the last few months, the media has been full of reports about insecure IoT devices that did not fulfill even the most basic security requirements. One of the concerns raised was the confidentiality of data being transferred from devices to cloud services provided by the manufacturers. In many cases, data is sent over public networks fully unencrypted, which is quite surprising, given that all of the popular TCP/IP-based transport protocols used in today’s IoT devices (e.g., HTTP and MQTT) support the negotiation and use of a secure (encrypted) transport channel by means of Transport Layer Security (TLS).

Eclipse Hono has supported the use of TLS in its HTTP and MQTT protocol adapters from the very beginning. The recently released 0.9-M2 milestone has added support for the authentication of devices using an X.509 client certificate as part of the TLS handshake for both the HTTP and the MQTT adapter. This allows devices to use a private/public key pair instead of a username and password for authenticating themselves to the protocol adapters.

Calling all developers

Europe's largest IoT hackathon returns to Berlin on May 14-15, 2019. Join more than 700 developers in various domain-specific hack challenges to hack, play, learn, have fun, and make new friends from all over the world!

Join the IoT hackathon

In this blog post I will walk you through a full example of how to create and register a tenant-specific trust anchor, create a certificate for a device, register its subject distinguished name and, finally, use the certificate to authenticate the device to Hono’s MQTT protocol adapter. In the remainder of this post, I will assume that you have a general understanding of RSA-based cryptography and, in particular, the roles played by private and public keys. For reference, RFC 5280 defines all the technical details of X.509.

Why client certificates?

When employing passwords for authenticating devices, the password of each device needs to be registered with Hono’s Credentials service so the protocol adapters can compare the password presented by the device during authentication with the password’s hash on record.

One of the advantages of using client certificates for authenticating devices is that it is no longer necessary to register individual secrets (passwords) for devices with Hono. Instead, it is enough to register a single trust anchor for a tenant which can then be used to verify the identity of all devices belonging to the tenant as part of the TLS handshake. In order for this to work, the client certificates used by the devices must contain a digital signature which can be validated using the public key that serves as the tenant’s trust anchor.

Create a tenant certificate authority

The first step, therefore, is to create the tenant’s public/private key pair that will be used to sign the client certificate(s) used by the tenant’s devices.

$ 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"

The subject distinguished name set using the `-subj` parameter may contain any valid X.500 distinguished name. However, in order to keep things simple you should refrain from using any attribute types apart from `CN`, `L`, `ST`, `O`, `OU`, `C`, `STREET`, `DC`, `UID`.

Register the tenant

Now that the keys have been created, we can register a tenant using the public key as the trust anchor.

For convenience we will be using the Hono Sandbox. However, any other (local) installation running version 0.9-M2 or later should work as well.

In the commands below, please replace the `ACME` tenant identifier with an identifier of your own choice. This is important because Hono enforces the uniqueness of tenant identifiers. Each identifier can therefore be registered once only per Hono instance.

The first three commands define some variables for later use: the tenant identifier, the certificate’s subject distinguished name and the Base64 encoded public key. The variables are then used in the command to register the trust anchor with the new tenant.

$ 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 <<EOS > 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

Create a device certificate

The next step is to create a key pair for the device and its corresponding client certificate, which is signed by the tenant’s private key.

$ 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

Again, make sure to not use any attribute types apart from `CN`, `L`, `ST`, `O`, `OU`, `C`, `STREET`, `DC`, `UID` in the subject distinguished name.

Register the device

We can now use an arbitrary device identifier to register the device with the tenant.

$ curl -i -H 'Content-Type: application/json' --data-binary '{"device-id": "hot-fuzz"}'$TENANT

Register the device’s subject DN

The final step is to register the device’s subject distinguished name. Again, make sure to use the same tenant and device identifiers as above.

$ SUBJECT=$(openssl x509 -in device-cert.pem -noout -subject -nameopt RFC2253 | sed s/^subject=//) $ cat <<EOS > 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$TENANT

Test the connection

Now that the device has been registered, it is time to connect to the MQTT adapter using the newly created client certificate and publish some data.

First, we start a consumer for the tenant that we registered the device for. You can download the client from the Hono web site:

$ java -jar hono-cli-*-exec.jar --hono.client.port=15671 --hono.client.tlsEnabled=true --hono.client.username=consumer@HONO --hono.client.password=verysecret$TENANT

In the final step, we use the Eclipse Mosquitto command line client to publish some telemetry data:

$ mosquitto_pub -h -p 8883 --capath /etc/ssl/certs/ --cert device-cert.pem --key device-key.pem -q 1 -t telemetry -m "Hello there"

If all goes well you should be able to see the data being logged to the console in the terminal where you have started the consumer.

The device may also use HTTP to publish data:

$ curl -i --cert device-cert.pem --key device-key.pem -H 'Content-Type: plain/text' -H 'Expect:' --data-binary 'Hello there'

Read more

How the open source project Eclipse Hono addresses the topic of IoT device connectivity.

The goal of the open source project Eclipse Ditto is to establish a framework for digital twins. Take a closer look.

Bosch pursues an open source strategy. Find out why.

We adopted Kubernetes for the Bosch IoT Suite. What led to this decision?

The IoT needs Kubernetes. Let us explain why.

The Bosch IoT Suite voted "best in class" in IoT platforms based on open source.