Bosch IoT Device Management - will be discontinued by mid 2024

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.

The device connectivity layer relies on protocol adapters to establish a device’s identity before it is allowed to publish telemetry data or send events.
Conceptually, the device connectivity layer 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 Messaging component of the device connectivity layer.

Every device connecting to the device connectivity layer needs to be registered in the scope of a single tenant. The Credentials APIs therefore requires a tenant identifier to be passed in to their operations. Consequently, the first step a protocol adapter needs to take when authenticating a device is determining the tenant that the device belongs to.

The means used by a device to indicate the tenant that it belongs to vary according to the type of credentials and authentication mechanism being used.


Table of contents:


Username and password based device authentication

In case of username and password device authentication, the password can be provided to the 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. The device connectivity layer will add salt and hash it.
    An example for plaintext password is given below:

    {
    "device-id": "my.namespace: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.
    The device connectivity layer 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": "my.namespace:4711",
    "type": "hashed-password",
    "auth-id": "little-sensor",
    "enabled": true,
    "secrets": [
    {
    "password-base64": "aHViMTIz"
    }
    ]
    }

X.509 Certificate based device authentication

Devices can also use an X.509 (client) certificate to authenticate to protocol adapters. In that case, the auth-id property will be the subject-dn of the client certificate in the format defined in RFC 2253.

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 see Manage CA certificates.

During certificate based authentication the protocol adapter tries to verify that a valid client certificate presented by the device is signed by one of the trusted root certificates configured for the device’s tenant.

During connection establishment with the device, the protocol adapter tries to determine the tenant (to which the device belongs) and to retrieve the tenant’s configuration information using the Tenants API. The adapter then uses the trust anchors that have been configured for the tenant to verify the client certificate.

The protocol adapter tries to look up the device’s tenant configuration first of all using the issuer DN from the device’s client certificate.
If that fails, and if the device has included the Server Name Indication extension during the TLS handshake, the adapter extracts the first label of the first host name conveyed in the SNI extension and look up for a tenant using the extracted label as the tenant identifier.
For example, a host name my-tenant.http.bosch-iot-hub.com would result in a tenant identifier of my-tenant being used in the look-up.

After having verified the client certificate using the trust anchor(s), the protocol adapter extracts the client certificate’s subject DN and calls the Credentials API in order to retrieve the x509-cert type credentials that are on record for the device.

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

{
"device-id": "my.namespace: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.

Generating an auth-id property

As mentioned, when using X.509 certificate authentication the auth-id property will be the subject-dn of the client certificate in the format defined in RFC 2253.

The auth-id can be generated from the device certificate using the following command:

openssl x509 -in <device certificate> -noout -subject -nameopt RFC2253 | sed s/^subject=//

For example if we have the following Subject fields in the certificate:

C = DE
E = myemail@acme.com
CN = B0102030405
OU = unit1
O = ACME Inc.

The generated auth-id will be:

C=DE,emailAddress=myemail@acme.com,CN=B0102030405,OU=unit1,O=ACME Inc.

Keep in mind that the auth-id property supports fields in dotted-decimal form with OID.

If your subject-dn includes fields that are not part of the list defined by RFC 2253 they will be automatically converted into dotted-decimal form upon save at your Credential API.

CA certificates

By default, the CA certificate is tenant-unique and can be used only within the scope of a single subscription.
Therefore, uploading the same CA certificate for multiple tenants is not possible.

However, there are use cases, where several tenants within an organization may need to share the same CA certificate.
For example, large-scale organizations may have multiple tenants within their setup, such as separate tenants for development, testing, and production purposes.
As the same devices may go through the different stages, and respectively tenants, it may simplify the workflow, if they can be authenticated with a single organization-wide CA certificate.
This CA certificate sharing is realized by creating a trusted anchor group where you provide the tenant IDs of the tenants that will be allowed to share the CA certificate.

Extracting tenant ID during device authentication

When the CA certificate is unique per tenant, the identification of tenantId during device authentication is fulfilled on the basis of the subject-dn of the CA certificate.

When the CA certificate is unique per tenant group, the identification of tenantId during device authentication is fulfilled on the basis of the Server Name Indication (SNI) during the TLS handshake. For that purpose, the unique tenant identifier tenant-alias must be provided as a prefix to the SNI.

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 Credentials API as a field of the secrets in the following format:

{
"device-id": "my.namespace:4711",
"type": "psk",
"auth-id": "little-sensor-2",
"enabled": true,
"secrets": [
{
"key": "AQIDBAUGBwg="
}
]
}

PSK based device authentication is currently only supported by CoAP protocol adapter.

Certificate revocation

The device connectivity layer 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.

The device connectivity layer does not provide native support neither for CRL (certificate revocation list) nor for OCSP (online certificate status protocol) mechanisms.