Device authentication

Devices connect to protocol adapters in order to publish telemetry data or events. Downstream applications consuming this data often take particular actions based on the content of the messages. Such actions may include simply updating some statistics, e.g. tracking the average room temperature, but may also trigger more serious activities like shutting down a power plant. It is therefore important that applications can rely on the fact that the messages they process have in fact been produced by the device indicated by a message’s source address.

Bosch IoT Hub relies on protocol adapters to establish a device’s identity before it is allowed to publish telemetry data or send events. Conceptually, Bosch IoT Hub distinguishes between two identities

  • an identity associated with the authentication credentials (termed the authentication identity or auth-id), and
  • an identity to act as the device identity or device-id.

A device therefore presents an auth-id as part of its credentials during the authentication process which is then resolved to a device identity by the protocol adapter on successful verification of the credentials.

In order to support the protocol adapters in the process of verifying credentials presented by a device, the Credentials API provides means to look up secrets on record for the device and use this information to verify the credentials.

The Credentials API supports registration of multiple sets of credentials for each device. A set of credentials consists of an auth-id and some sort of secret information. The particular type of secret determines the kind of information kept. Based on this approach, a device may be authenticated using different types of secrets, e.g. a hashed password or certificates, depending on the capabilities of the device.

Once the protocol adapter has resolved the device-id for a device, it uses this identity when referring to the device in all subsequent API invocations, e.g. when forwarding telemetry messages downstream to the Bosch IoT Hub Messaging component.

Username and password based device authentication

In case of username and password device authentication, the password can be provided to the IoT Hub Credentials API as a field of the secrets array field in the 2 following formats:

  1. Plaintext password (password field): this format is recommended to use. Provide the plaintext password string in the password field. Bosch IoT Hub will add salt and hash it. An example for plaintext password is given below:

    {
     "device-id": "4711",
     "type": "hashed-password",
     "auth-id": "little-sensor",
     "enabled": true,
     "secrets": [
       {
         "password": "plaintextPassword"
       }
     ]
    }
    
  2. Base64 encoded password: (password-base64 field): provide the base64 encoded password in the password-base64 field. Bosch IoT Hub will add salt and hash it. This format should be used for real world scenarios if the passwords contain special characters. An example for Base64 encoded password for plaintext password “hub123” is given below:

    {
     "device-id": "4711",
     "type": "hashed-password",
     "auth-id": "little-sensor",
     "enabled": true,
     "secrets": [
       {
         "password-base64": "aHViMTIz"
       }
     ]
    }
    

X.509 Certificate based device authentication

In case of device certificate, the auth-id property will be the subject-dn of the client certificate in the format defined in RFC 2253.

To create a certificate credentials, the details of the certificate can be provided to the IoT Hub Credentials API as a field of the secrets array field in the following format:

{
  "device-id": "4711",
  "type": "x509-cert",
  "auth-id": "CN=device-1,O=ACME Corporation",
  "enabled": true,
  "secrets": [{}]
}

Once you have created device credentials as shown above, your devices can then authenticate using those device certificates.

The example above does not contain any of the not-before and not-after properties. The not-before and not-after properties should be omitted if the validity period is the same as the period indicated by the client certificate’s corresponding properties. It is still necessary to provide a (empty) JSON object in the secrets array, though. The validity period indicated by the client certificate’s property will be automatically checked by the X.509 library.

Prerequisites:

For any device certificate to be recognized, the CA certificate with which the device certificate was signed has to be uploaded to your tenant. For details, refer to Manage CA certificates.

PSK (pre-shared key) based device authentication

In case of PSK device authentication, the pre-shared key can be provided as a base64 encoded string to the IoT Hub Credentials API as a field of the secrets in the following format:

 {
  "device-id": "4711",
  "type": "psk",
  "auth-id": "little-sensor-2",
  "enabled": true,
  "secrets": [
    {
      "key": "AQIDBAUGBwg="
    }
  ]
 }
Note
PSK based device authentication is currently only supported by CoAP protocol adapter.

Certificate revocation

Bosch IoT Hub has a white-listing approach in place. Devices can connect with a client certificate, only if a corresponding X.509 credential has been registered for this device. The credentials have an enabled flag which can be set to false preventing the device from connecting using its certificate.

As of today Bosch IoT Hub does not provide native support either for CRL (certificate revocation list) or for OCSP (online certificate status protocol) mechanisms.

Corporate information Data protection notice Legal information Support Free plans