How to set up client certificate-based authentication for devices

Introduction

Bosch IoT Rollouts supports device authentication with client certificates. This guide demonstrates how to leverage this feature on Rollouts EU1 and EU2.

Applicable to Rollouts customers of

  • Rollouts EU1 - Bosch IoT Suite portal
  • Rollouts EU2 - Bosch IoT Cloud catalog

Prerequisites

  • A booked Bosch IoT Rollouts service instance on Bosch IoT Suite (EU1) or Bosch IoT Cloud (EU2).
  • You have OpenSSL and a curl with OpenSSL support installed on your client machine.

On MAC OS X this can be achieved with:

$ brew install curl --with-openssl
$ export PATH=/usr/local/opt/curl/bin:$PATH

Generate RootCA key

$ openssl req -new -keyout cakey.pem -out careq.pem

Sign the RootCA certificate

$ openssl x509 -signkey cakey.pem -req -days 365 -in careq.pem -out caroot.cer -extensions v3_ca

Create your certificate signing request (CSR) for your device client certificate

CN has to be equal to desired controllerID in Rollouts, e.g. in this example testDevice01.

$ openssl genrsa -des3 -out client.key 4096
$ openssl req -new -key client.key -out client.csr

Expected result is something similar to:

$ openssl req -text -noout -verify -in client.csr

verify OK
Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C=DE, ST=BW, L=WA, O=Bosch Software Innovations GmbH, OU=Rollouts, CN=testDevice01
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
.
.
.

Sign our client certificate

Create start serial number and sign the certificate with your authority.

$ echo 1234 > serial.txt
$ openssl x509 -CA caroot.cer -CAkey cakey.pem -CAserial serial.txt -req -in client.csr -out client.cer -days 365

Expected result:

Signature ok
subject=/C=DE/ST=BW/L=WA/O=Bosch Software Innovations GmbH/OU=Rollouts/CN=testDevice01

Check the signed certificate

$ openssl x509 -in client.cer -text -noout

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 4661 (0x1235)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=DE, ST=BW, L=WA, O=Bosch Software Innovations GmbH, OU=Rollouts, CN=Rollouts Test CA/emailAddress=service-rollouts@bosch-si.com
        Validity
            Not Before: Mar 28 07:30:55 2017 GMT
            Not After : Mar 28 07:30:55 2018 GMT
        Subject: C=DE, ST=BW, L=WA, O=Bosch Software Innovations GmbH, OU=Rollouts, CN=testDevice01
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (4096 bit)
.
.
.

Get fingerprint of root CA

This step depends on the Rollouts environment (EU1 vs. EU2).

Bosch IoT Suite (EU1)

On Bosch IoT Suite, you need to extract the SHA-256 fingerprint:

openssl x509 -noout -fingerprint -sha256 -inform pem -in caroot.cer 

Expected result is something similar to:

SHA256 Fingerprint=D3:D0:ED:F2:A8:98:90:0F:53:16:D0:5D:08:F7:C0:0E:BB:6A:5E:C6:3D:C4:E5:86:88:D8:2A:E2:4A:72:86:40

Bosch IoT Cloud (EU2)

On Bosch IoT Cloud, you need to extract the MD-5 fingerprint:

$ openssl x509 -noout -fingerprint -md5 -inform pem -in caroot.cer

Expected result is something similar to:

MD5 Fingerprint=7F:A0:1C:9B:1D:11:25:43:3B:5B:D9:ED:00:9C:1F:A4

Enter fingerprint into your Rollouts tenant configuration

Enter the fingerprint of the previous step into the UI.

Set issuer hash

Combine certificate and chain into one file

For authentication, the device needs to send the entire certificate chain along with the request. Bosch IoT Rollouts will then validate the certificate chain and extract the fingerprints from all certificates. To finally establish trust with the client certificate provided by the device, the root or intermediate CA’s certificate fingerprint is checked against the fingerprint that is stored in the tenant configuration.

To assemble the certificate chain, you can concatenate the single .cer files:

$ cat client.cer caroot.cer > chain.cer

Run DDI query leveraging the certificate

You can now send requests to DDI by attaching the certificate chain file. Note that the certificate-enabled DDI base URL depends on the Rollouts environment (EU1 vs. EU2).

On Bosch IoT Suite (EU1), the DDI base URL that supports certificate-based authentication is

device-cert.eu1.bosch-iot-rollouts.com

On Bosch IoT Cloud (EU2), the DDI base URL that supports certificate-based authentication is

rollouts-cs.secure-apps.de1.bosch-iot-cloud.com

DDI query example for Bosch IoT Cloud (EU2):

$ curl -i -k --cert ./chain.cer --key ./client.key https://rollouts-cs.secure-apps.de1.bosch-iot-cloud.com/YOUR-TENANT/controller/v1/testDevice01

Expected result:

{
  "config": {
    "polling": {
      "sleep": "00:05:00"
    }
  },
  "_links": {
    "configData": {
      "href": "https://rollouts-cs.secure-apps.de1.bosch-iot-cloud.com/YOUR-TENANT/controller/v1/testDevice01/configData"
    }
  }
}
Device Registered